openapi: 3.0.0
info:
  title: PipesHub API
  description: |
    Unified API documentation for PipesHub services.

    PipesHub is an enterprise-grade platform providing:
    - User authentication and management
    - Document storage and version control
    - Knowledge base management
    - Enterprise search and conversational AI
    - Third-party integrations via connectors
    - System configuration management
    - Crawling job scheduling
    - Email services

    ## Authentication
    Most endpoints require JWT Bearer token authentication. Some internal endpoints use scoped tokens for service-to-service communication.

    **OAuth 2.0 Bearer tokens** from `POST /oauth2/token` use the same `Authorization: Bearer` header. For **`client_credentials`**, machine tokens may encode `userId === client_id` in the JWT; the **Node API gateway** resolves the application's **token identity** — the service account it is pointed at (`tokenIdentityUserId`), or its creator for an application registered before that was required and never bound, and sets the authenticated user accordingly. It reads the application record on every request, and a token minted for a different identity than the app's current one is refused with `401`. See the **OAuth Provider** tag for full behavior.

    ## Behaviour common to every route
    App-level middleware runs before any router, so the following applies to every operation below, before authentication, unless an exception is named.

    **Markup filter.** A query value, or any string in a JSON or form-encoded body, that looks like markup is refused with `400 HTTP_BAD_REQUEST`. The message names where the value was, for example `HTML tags, scripts, and XSS content are not allowed in the field "name".` or `... in the query parameter "search".` (a field name that is not a plain identifier path reads `the request`), and says what counted: text in angle brackets such as `<id>` counts as an HTML tag, an encoded script tag counts, or script content such as `onclick=`, `javascript:` or `data:text/html` counts. A string over 100,000 characters is refused as too long to check instead: `The value of the field "name" is longer than 100,000 characters, which is too long to check for HTML tags and scripts. Please shorten it and try again.` It looks for an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), and any string longer than 100,000 characters. A string the filter lets through is rewritten before the route sees it: the filter trims surrounding whitespace, drops a lone `<` together with everything after it (`a < b` arrives as `a`), and escapes `>` as `&gt;`. POST and PUT under `/agents/`, `/conversations/`, `/connectors` and `/api-toolsets`, and POST, PUT and PATCH under `/skills`, skip the filter. So does the question of a search: the `query` string of a JSON body sent to `POST /search` or `POST /retrieve` is neither checked nor rewritten, unless it is longer than 100,000 characters.

    **Body parsers.** `application/json` bodies (up to 10 MB, 5 MB on `/mcp`) and `application/x-www-form-urlencoded` bodies (up to 100 KB and 1000 fields) are parsed for every method. A JSON body that does not parse, or a body shorter or longer than its `Content-Length`, is answered `400 HTTP_BAD_REQUEST` (`The request body is not valid JSON.`, `The request body does not match its Content-Length.`), a body past these limits `413 HTTP_PAYLOAD_TOO_LARGE`, and an unsupported content encoding or character set `415 HTTP_UNSUPPORTED_MEDIA_TYPE`; a JSON body over 5 MB on `/mcp` gets its `413` as a JSON-RPC error (see `POST /mcp`). Form values arrive as text and the request validators do not convert them, so a number, a boolean or a free-form object sent form-encoded is refused (`400 VALIDATION_ERROR`) or read as a string. A list sent form-encoded is read as a list only when its key repeats, so a single value or an empty list cannot be sent. The form media type is therefore listed only on operations whose body is a flat object of text fields: every value a string (string enums included), with no lists or nested objects.

    **Request size.** On every route with a request validator, the body, query and path values are measured before the schema runs. An array over 10,000 items (`<path> can have at most 10000 items.`), an object over 10,000 keys (`<path> can have at most 10000 fields.`), more than 100,000 array items and object keys in the whole request (`The request holds too many items in total (the limit is 100000); the limit is reached at <path>.`) or nesting deeper than 64 levels (`<path> is nested more than 64 levels deep.`) is refused with `400 VALIDATION_ERROR` (detail code `TOO_BIG`, or `TOO_DEEP` for nesting; the path reads like `body.items`). The deployment can change the first three limits with `VALIDATION_MAX_ARRAY_LENGTH`, `VALIDATION_MAX_OBJECT_KEYS` and `VALIDATION_MAX_TOTAL_ITEMS`.

    **OAuth scopes.** On an operation whose `security` names `oauth2` scopes, an OAuth access token holding none of them gets `403 HTTP_FORBIDDEN` ("Insufficient scope. Required: ...") right after authentication. Session tokens are never scope-checked.

    **No such route.** A method and path that no route handles get Express's own `404` page, `text/html`, reading `Cannot <METHOD> <path>`. Such pairs are not listed as operations.

    ## Base URLs
    All endpoints use the `/api/v1` prefix unless otherwise noted.

    ## Query parameter names
    On every `/api/v1` and `/mcp` endpoint, a query parameter whose name starts with `$` or contains `.` (including a nested name such as `filter[$ne]` or `a.b`) is refused with `400` and error code `VALIDATION_ERROR`. Only names are checked: values may contain dots, such as file names.
  version: 1.0.0
  contact:
    name: API Support
    email: support@pipeshub.com
servers:
- url: '{instance_url}/api/v1'
  description: Base API URL
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL (without /api/v1)
- url: '{instance_url}'
  description: Root URL (used for MCP endpoints mounted at /mcp)
  variables:
    instance_url:
      default: https://app.pipeshub.com
      description: Base server URL
tags:
- name: User Account
  description: User authentication including multi-step MFA, password reset, OTP login, and token management
- name: Organization Auth Config
  description: Admin configuration of authentication methods including MFA steps and allowed providers
- name: OAuth Provider
  description: |
    PipesHub OAuth 2.0 Authorization Server implementing RFC 6749, RFC 7636 (PKCE), and OpenID Connect.

    **Supported Grant Types:**
    - `authorization_code` - Standard OAuth flow with PKCE support
    - `client_credentials` - Machine-to-machine authentication
    - `refresh_token` - Token refresh for long-lived access
    - `urn:ietf:params:oauth:grant-type:device_code` - Device authorization grant (RFC 8628) for devices and CLIs without a browser; started with `POST /oauth2/device_authorization`

    **Dynamic Client Registration (RFC 7591):** `POST /oauth2/register`, only when the instance enables it.

    **Security Features:**
    - PKCE (Proof Key for Code Exchange) for public clients
    - State parameter for CSRF protection
    - Configurable token lifetimes
    - Token revocation and introspection

    **OpenID Connect:**
    - ID tokens with standard claims
    - UserInfo endpoint for profile data
    - Discovery endpoint for automatic configuration

    **Machine tokens (`client_credentials`) — gateway and downstream identity:**
    Access tokens may encode **`userId === client_id`**. The **Node.js API gateway** resolves the effective user to the application's **token identity**: the service account it is pointed at (**`tokenIdentityUserId`**), or its creator for an application registered before a service account was required and never bound. It loads the application by **`client_id`** on every such token and takes the identity from that record.

    The JWT's **`createdBy`** claim is a cross-check rather than a source: despite its name it carries the identity, not who registered the application, and a token whose claim disagrees with the record is refused with **401** ("This token was issued for an identity the application no longer acts as"), and so is a token whose app was deleted ("OAuth app not found or revoked"). Pointing an application at a different service account also revokes the tokens it has already issued, so a stale claim should not arrive in the first place.

    **Python services:** Validate `Authorization: Bearer` as today and use the JWT payload’s **`userId`** as-is for scopes and user-scoped logic. Where a machine token carries **`userId === client_id`** and a **`createdBy`** claim, Python copies that claim onto **`userId`** first, so both halves of the product agree on the identity.

    **Operational note:** Prefer tokens whose JWT already carries the identity as **`userId`**; use **`POST /oauth-clients/{appId}/revoke-all-tokens`** and obtain new tokens from **`POST /oauth2/token`** when rotating integrations.
- name: OAuth Apps
  description: |
    Manage OAuth 2.0 client applications registered with PipesHub.

    OAuth apps allow third-party applications to access PipesHub APIs on behalf of users
    or organizations. Each app receives a client ID and secret for authentication.

    **Who can see which apps**
    - **Everyone (including org admins)** sees and manages only OAuth apps **they created** (`createdBy`). Other members' apps are hidden (not listed; individual operations return not found).

    **Session only**
    - Every `/oauth-clients/*` route requires the user's interactive session JWT. OAuth access tokens and personal access tokens (`phpat_...`) are rejected with `403`, so a token issued to a client can never register, reconfigure, or revoke clients on its own.

    **Who authorizes vs. client credentials**
    - **Authorization code:** Any authenticated user in the workspace may complete consent for a valid `client_id`; issued tokens represent **that user**.
    - **Client credentials:** Access tokens represent the **service account the app is pointed at**, never the caller. An app that allows this grant must name one at creation, and only an administrator may choose it. Apps created before that rule, and never bound, still represent the **OAuth app creator** — the fallback this rule exists to remove.

    **Scopes**
    - `GET /oauth-clients/scopes` returns scopes grouped by category for the **signed-in user's role**.
    - **Org admins** may register apps that request additional **admin-only** scopes; non-admins cannot select those scopes when creating or updating an app.

    **App Types:**
    - **Confidential clients**: Server-side apps that can securely store secrets
    - **Public clients**: Browser/mobile apps that cannot securely store secrets (use PKCE)

    **App Lifecycle:**
    - Create apps with name, redirect URIs, allowed scopes, and optional URLs (homepage, privacy, terms)
    - Regenerate secrets if compromised
    - Suspend/activate apps to control access
    - Revoke all tokens for emergency access removal
- name: Personal Access Tokens
  description: |
    Self-service, long-lived, scoped, revocable credentials that act as their
    creator — unlike an OAuth app's `client_credentials` flow, which acts as
    the app.

    **Who can create one**
    - **Any authenticated org member** — unlike OAuth apps, this is
      deliberately not admin-gated.

    **Session only**
    - Every `/personal-access-tokens/*` route requires the user's interactive
      session JWT. OAuth access tokens and personal access tokens (`phpat_...`)
      are rejected with `403`. `scopes` is capped at the instance's `MCP_SCOPES`,
      not at the caller's own token, so a narrowly scoped token could otherwise
      mint itself a full-scope, non-expiring PAT.

    **How it's issued**
    - Minted through the same OAuth access-token machinery as `/oauth2/token`,
      against one lazily-created, per-org synthetic OAuth app
      (`clientId: pat-system:<orgId>`) that every PAT in that org shares.
      That app is hidden from `/oauth-clients/*` — it never appears in your
      own OAuth app list and can't be managed through those routes.
    - The raw token is prefixed `phpat_` ahead of the underlying JWT (see the
      `bearerAuth` security scheme) so it's recognizable to secret scanners.
      It's shown exactly once, at creation.

    **Expiry and scopes**
    - `expiryDays`: `30` (default), `90`, `365`, or `never`.
    - Scopes default to the org's full configured `MCP_SCOPES` set if none
      are requested; `GET /personal-access-tokens/scopes` lists what's
      available.

    **Admin visibility**
    - Regular members only ever see and revoke their own tokens.
    - Org admins can list and revoke *any* member's token via
      `/personal-access-tokens/admin*` — for incident response (a departed
      employee, a compromised laptop) — without needing the OAuth app CRUD
      access described above.
- name: OpenID Connect
  description: |
    OpenID Connect 1.0 endpoints for identity federation and discovery.

    **Discovery:**
    - `/.well-known/openid-configuration` - Authorization server metadata
    - `/.well-known/oauth-authorization-server` - Authorization server metadata (RFC 8414)
    - `/.well-known/oauth-protected-resource/mcp` - Protected resource metadata (RFC 9728)
    - `/.well-known/jwks.json` - Public keys for token verification

    **UserInfo:**
    - `/oauth2/userinfo` - Get authenticated user's profile information

    **Supported Claims:**
    - `user_id` - User identifier
    - `email`, `email_verified` - Email information
    - `name`, `given_name`, `family_name` - Name information
- name: Organizations
  description: Organization management operations
- name: Knowledge Base
  description: Knowledge base management operations
- name: Knowledge Hub
  description: Unified browse API for root and child nodes (apps, record groups, folders, records) with filtering and search
- name: Connector
  description: Connector-related operations
- name: Conversations
  description: AI-powered conversational chat management with citations and follow-up questions
- name: Semantic Search
  description: Enterprise semantic search across all indexed knowledge with relevance scoring
- name: Agents
  description: Custom AI agents with specialized capabilities and tool integrations
- name: Connector Registry
  description: Browse available connector types and their configuration schemas
- name: Connector Instances
  description: Create, manage, and delete connector instances for your organization
- name: Connector Configuration
  description: Configure authentication, sync settings, and filters for connectors
- name: Connector Control
  description: Enable/disable connectors for sync or agent functionality
- name: Connector OAuth
  description: OAuth 2.0 authorization flow for connectors requiring user consent
- name: Connector Filters
  description: Dynamic filter options for selecting which data to sync
- name: OAuth Configuration
  description: Admin management of OAuth credentials for connector types
- name: AI Models Providers
  description: Manage individual AI model providers - add, update, delete, and set defaults.
- name: Web Search
  description: Manage web search providers (DuckDuckGo, Serper, Tavily, Exa) and settings for internet search.
components:
  parameters:
    RevealStoredSecrets:
      name: reveal
      in: query
      required: false
      description: |
        Set to `true` to receive stored secrets instead of placeholders. Honoured only for an
        admin's own configuration where the deployment allows it (see `GET
        /configurationManager/secretReveal`); ignored for OAuth-app tokens and any other value.
      schema:
        type: string
        enum:
        - 'true'
  headers:
    X-Conversation-Id:
      description: |
        Id of the conversation this turn wrote to. Sent on success and on
        failure, so a caller whose first turn failed can still fetch or
        continue that conversation.
      schema:
        type: string
        format: objectId
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        JWT Bearer token for authenticated requests.

        A personal access token (see the **Personal Access Tokens** tag) is a
        `phpat_`-prefixed variant of this same JWT — e.g. `phpat_eyJhbGci...`.
        The prefix is display-only, added for secret-scanner detectability; the
        gateway strips it before verifying the token, so send it exactly as
        issued, prefix included.
    scopedToken:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        Scoped JWT token for service-to-service authentication.
        Format: "Bearer {scoped_token}"
        Required scopes vary by endpoint.
    oauth2:
      type: oauth2
      description: |
        OAuth 2.0 authentication with fine-grained scopes.
        Supports authorization_code (with PKCE) and client_credentials flows.
        OAuth tokens are Bearer JWTs — use the same Authorization header as regular tokens.
        For **client_credentials**, machine JWTs may use `userId === client_id`; the Node gateway resolves the application's token identity — the service account it is pointed at, or its creator for an application registered before that was required — see **OAuth Provider** tag.
      flows:
        authorizationCode:
          authorizationUrl: /api/v1/oauth2/authorize
          tokenUrl: /api/v1/oauth2/token
          refreshUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:read: Read semantic search results and history
            semantic:write: Execute semantic search
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            toolset:read: Read toolsets and their authentication status
            toolset:write: Add, configure and authenticate toolsets
            toolset:delete: Remove toolsets and their credentials
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            code:read: Read indexed code repositories and their code graph
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
            crawl:delete: Delete crawling jobs
            skill:read: Read custom agent skills
            skill:write: Create and manage custom agent skills
            mcp:read: Read MCP servers and their tools
            mcp:write: Add, configure and authenticate MCP servers
            mcp:delete: Remove MCP servers and their credentials
        clientCredentials:
          tokenUrl: /api/v1/oauth2/token
          scopes:
            openid: OpenID Connect authentication
            profile: User profile information
            email: User email address
            offline_access: Offline access (refresh tokens)
            org:read: Read organization information
            org:write: Update organization settings
            org:admin: Full organization administration
            user:read: Read user profiles
            user:write: Update user profiles
            user:invite: Invite new users
            user:delete: Delete users
            usergroup:read: Read user groups
            usergroup:write: Create and manage user groups
            team:read: Read team information
            team:write: Create and manage teams
            kb:read: Read knowledge bases and records
            kb:write: Create and update knowledge bases
            kb:delete: Delete knowledge bases and records
            kb:upload: Upload files to knowledge bases
            semantic:write: Execute semantic search
            semantic:read: Read semantic search results and history
            semantic:delete: Delete semantic search history
            conversation:read: Read conversations
            conversation:write: Create and manage conversations
            conversation:chat: Send messages in conversations
            project:read: Read projects and their conversations
            project:write: Create and manage projects
            project:delete: Delete projects
            agent:read: Read AI agents
            agent:write: Create and manage AI agents
            agent:execute: Execute AI agents
            toolset:read: Read toolsets and their authentication status
            toolset:write: Add, configure and authenticate toolsets
            toolset:delete: Remove toolsets and their credentials
            connector:read: Read connector configurations
            connector:write: Create and update connectors
            connector:sync: Trigger connector synchronization
            connector:delete: Delete connectors
            code:read: Read indexed code repositories and their code graph
            config:read: Read system configuration
            config:write: Update system configuration
            crawl:read: Read crawling jobs
            crawl:write: Create and manage crawling jobs
            skill:read: Read custom agent skills
            skill:write: Create and manage custom agent skills
            mcp:read: Read MCP servers and their tools
            mcp:write: Add, configure and authenticate MCP servers
            mcp:delete: Remove MCP servers and their credentials
  schemas:
    AuthMethod:
      type: object
      additionalProperties: false
      description: Authentication method configuration
      properties:
        type:
          type: string
          enum:
          - otp
          - password
          - google
          - microsoft
          - github
          description: |
            Type of authentication method:
            - `password`: Email/password authentication
            - `otp`: One-time password via email (6-digit, expires in 10 minutes)
            - `google`: Google OAuth 2.0
            - `microsoft`: Microsoft OAuth 2.0
            - `github`: accepted and stored, but no sign-in flow implements it:
              `/userAccount/initAuth` never lists it and `/userAccount/authenticate` answers `400`

            `samlSso`, `oauth` (removed in 1.0) and `azureAd` (now `microsoft`) are refused when a
            policy is saved. A stored policy that still names one is read without it (`azureAd`
            reads as `microsoft`), with `password` added to the first step.
      required:
      - type
    AuthStep:
      type: object
      additionalProperties: false
      description: A single step in multi-factor authentication flow
      properties:
        order:
          type: number
          description: |
            Label of the step; must be unique across steps. Only checked to be a number: `0`,
            negative, fractional and values above 3 are accepted and stored as sent. Sign-in runs
            the steps in ascending `order`, and `GET /orgAuthConfig/authMethods` returns them
            renumbered 1, 2, 3 in that order.
        allowedMethods:
          type: array
          items:
            $ref: '#/components/schemas/AuthMethod'
          description: List of allowed authentication methods for this step. User can choose any one method from this list. A method may appear only once in the whole policy.
          minItems: 1
          uniqueItems: true
      required:
      - order
      - allowedMethods
    AuthConfig:
      type: object
      additionalProperties: false
      description: |
        Organization authentication configuration. Supports 1-3 authentication steps for multi-factor authentication.
        **Validation Rules:**
        - Minimum 1 step, maximum 3 steps
        - Each step must have unique order
        - No duplicate methods within the same step
        - No method can appear in multiple steps
      properties:
        authMethods:
          type: array
          items:
            $ref: '#/components/schemas/AuthStep'
          description: List of authentication steps in order
          minItems: 1
          maxItems: 3
      required:
      - authMethods
    UpdateAuthMethodResponse:
      type: object
      additionalProperties: false
      description: Response after updating organization authentication methods
      properties:
        message:
          type: string
          example: Auth method updated
        authMethod:
          type: array
          description: Updated authentication steps (same shape as request body)
          items:
            $ref: '#/components/schemas/AuthStep'
      required:
      - message
      - authMethod
    OrgAuthConfigSetupResponse:
      type: object
      additionalProperties: false
      description: Response from setting up organization auth configuration
      properties:
        message:
          type: string
      required:
      - message
    InitAuthRequest:
      type: object
      additionalProperties: false
      description: |
        Optional JSON body for `/userAccount/initAuth`. Valid shapes include: omitting the body entirely, sending `{}` (empty object), or `{ "email": "<address>" }`. Neither the body nor `email` is required. When `email` is omitted, the session is still created and `allowedMethods` / `authProviders` are returned as usual; clients typically supply `email` later on `/userAccount/authenticate`. The `email` property remains supported mainly for legacy clients and backward compatibility. Fields other than `email` are dropped by the validator, not refused.
      properties:
        email:
          type: string
          format: email
          maxLength: 254
          pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\.)+[A-Za-z]{2,}$
          description: |
            Optional; retained for legacy reasons. When set, stored on the auth session for correlation with later `/authenticate` calls (RFC 5321 compliant address). When the property is present it must be a well-formed address of at most 254 characters: an empty string, `null` or a malformed address is answered `400`.
          example: user@example.com
    InitAuthResponse:
      type: object
      additionalProperties: false
      description: Response containing available authentication methods and session info
      properties:
        currentStep:
          type: integer
          description: Current authentication step (0-indexed). Always 0 for initial response.
          example: 0
        allowedMethods:
          type: array
          items:
            type: string
            enum:
            - otp
            - password
            - google
            - microsoft
          description: List of allowed authentication methods for the current step
          example:
          - password
          - google
          - otp
        message:
          type: string
          description: Response message
          example: Authentication initialized
        authProviders:
          $ref: '#/components/schemas/AuthProviders'
        jitEnabled:
          type: boolean
          description: True when at least one allowed external provider has JIT provisioning enabled
      required:
      - currentStep
      - allowedMethods
      - message
      - authProviders
      - jitEnabled
    AuthProviderGooglePublicConfig:
      type: object
      additionalProperties: false
      description: Public Google OAuth settings returned to clients
      properties:
        clientId:
          type: string
          description: Google OAuth client ID
        enableJit:
          type: boolean
          description: Whether just-in-time user provisioning is enabled for Google
    AuthProviderMicrosoftPublicConfig:
      type: object
      additionalProperties: false
      description: Public Microsoft OAuth settings returned to clients
      properties:
        tenantId:
          type: string
          description: Microsoft tenant ID
        clientId:
          type: string
          description: Microsoft OAuth client ID
        authority:
          type: string
          description: Sign-in authority URL, built on save as `https://login.microsoftonline.com/{tenantId}`
        enableJit:
          type: boolean
          description: Whether just-in-time user provisioning is enabled for Microsoft
    AuthProviders:
      type: object
      additionalProperties: false
      description: |
        Settings of the external sign-in providers among the allowed methods, keyed by provider.
        A provider is listed whenever its settings can be read, which is also the case when
        nothing has been saved for it yet: its entry is then an empty object. Only `google`
        and `microsoft` have a sign-in flow.
      properties:
        google:
          $ref: '#/components/schemas/AuthProviderGooglePublicConfig'
        microsoft:
          $ref: '#/components/schemas/AuthProviderMicrosoftPublicConfig'
    AuthenticateRequest:
      type: object
      additionalProperties: false
      description: |
        Request to authenticate using specified method.
        **Credential format varies by method:**
        - `password`: `{ password: "string" }`
        - `otp`: `{ otp: "123456" }` (6-digit code)
        - `google`: `"google-id-token-string"`, or `{ credential: "google-id-token-string" }`
        - `microsoft`: `{ idToken: "..." }`; an `accessToken` may be sent alongside but is not read

        SAML (`samlSso`), generic OAuth (`oauth`) and Azure AD (`azureAd`) sign-in were removed in 1.0
        and are answered `400`. Azure AD accounts sign in with `microsoft`.

        Any top-level field not listed here is refused with `400`.
      properties:
        method:
          type: string
          enum:
          - otp
          - password
          - google
          - microsoft
          description: |
            Authentication method to use. It must be one the session's current step allows;
            any other value, known or not, is answered `400`.
        credentials:
          anyOf:
          - $ref: '#/components/schemas/PasswordCredentials'
          - $ref: '#/components/schemas/OtpCredentials'
          - $ref: '#/components/schemas/GoogleCredentials'
          - $ref: '#/components/schemas/MicrosoftCredentials'
          - type: string
            minLength: 1
            description: Google ID token (for google method)
          description: |
            Credentials based on the authentication method; the shape each method needs is
            listed above. The validator only checks that this is a non-empty string or an
            object whose `password`, `otp`, `token`, `code`, `accessToken` and `idToken`,
            when present, are strings; other fields of the object are passed through. An
            object without the field its method needs is refused later as a failed sign-in,
            not as a validation error: `microsoft` without `idToken` answers `400`, and a Google
            token that is not a JWT answers `500`.
        email:
          type: string
          format: email
          maxLength: 254
          pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9-]*\.)+[A-Za-z]{2,}$
          description: |
            The account's email. Used when the session was started without one
            (`/initAuth` with no `email`); when neither carries an email, password and
            code sign-in answer `500`. Ignored by the external-provider methods, which
            take the email from the provider.
        cf-turnstile-response:
          type: string
          description: Cloudflare Turnstile CAPTCHA token (optional, if CAPTCHA is enabled)
      required:
      - method
      - credentials
    PasswordCredentials:
      type: object
      additionalProperties: false
      description: Credentials for password authentication
      properties:
        password:
          type: string
          description: User password
          format: password
      required:
      - password
    OtpCredentials:
      type: object
      additionalProperties: false
      description: Credentials for OTP authentication
      properties:
        otp:
          type: string
          description: 6-digit one-time password
          pattern: ^\d{6}$
          example: '123456'
      required:
      - otp
    AuthenticateMultiStepResponse:
      type: object
      additionalProperties: false
      description: Current authentication step succeeded; additional MFA steps remain
      properties:
        status:
          type: string
          enum:
          - success
          description: Step completion status
        nextStep:
          type: integer
          description: Next authentication step index
        allowedMethods:
          type: array
          items:
            type: string
          description: Allowed method types for the next step
        authProviders:
          $ref: '#/components/schemas/AuthProviders'
      required:
      - status
      - nextStep
      - allowedMethods
      - authProviders
    AuthenticateFinalResponse:
      type: object
      additionalProperties: false
      description: All authentication steps complete; JWT tokens returned
      properties:
        message:
          type: string
          description: Success message
          example: Fully authenticated
        accessToken:
          type: string
          description: JWT access token (1 hour expiry)
        refreshToken:
          type: string
          description: JWT refresh token (7 days expiry)
      required:
      - message
      - accessToken
      - refreshToken
    AuthenticateResponse:
      oneOf:
      - $ref: '#/components/schemas/AuthenticateMultiStepResponse'
      - $ref: '#/components/schemas/AuthenticateFinalResponse'
      description: |
        Either the next step in a multi-factor flow (`status`, `nextStep`, `allowedMethods`, `authProviders`)
        or final tokens (`message`, `accessToken`, `refreshToken`).
    AuthenticatedPasswordResetResponse:
      type: object
      additionalProperties: false
      description: Response after authenticated user changes password (new access token issued)
      properties:
        data:
          type: string
          example: password reset
        accessToken:
          type: string
          description: New JWT access token after password change
      required:
      - data
      - accessToken
    RefreshTokenResponse:
      type: object
      additionalProperties: false
      description: Response with new access token
      properties:
        user:
          $ref: '#/components/schemas/RefreshTokenUser'
        accessToken:
          type: string
          description: New JWT access token (24 hour default expiry, configurable via ACCESS_TOKEN_EXPIRY)
      required:
      - user
      - accessToken
    RefreshTokenUser:
      type: object
      additionalProperties: false
      description: User record returned with a refreshed access token
      properties:
        _id:
          type: string
          description: User ID
        orgId:
          type: string
          description: Organization ID
        email:
          type: string
          format: email
        fullName:
          type: string
        firstName:
          type: string
        lastName:
          type: string
        middleName:
          type: string
        mobile:
          type: string
          description: Mobile number (10-15 digits with optional +)
          pattern: ^$|^\+?[0-9]{10,15}$
        designation:
          type: string
        kind:
          type: string
          enum:
          - human
          - service
          description: |
            Whether this account is a person who signs in (`human`) or a
            machine identity that automation authenticates as (`service`).
            Absent on records written before service accounts existed, which
            are all human.
        description:
          type: string
          description: Free text explaining what a service account is for. Unused for people.
        isDisabled:
          type: boolean
          default: false
          description: |
            The account is suspended: its tokens stop working and no session
            can be issued, but the record, its group memberships and its
            permission-graph node survive so it can be switched back on.
        restoreOpId:
          type: string
          description: |
            Internal and transient. Present only while a deleted service
            account is being brought back, and cleared when that finishes
            either way. It lets the steps that complete or undo a restore tell
            their own attempt from a later one. Not something to depend on.
        role:
          type: string
          enum:
          - admin
          - member
          description: Organization role stored on the user document (`admin` or `member`)
        address:
          $ref: '#/components/schemas/Address'
        dataCollectionConsent:
          type: boolean
          description: Whether user has consented to data collection
        hasLoggedIn:
          type: boolean
        isDeleted:
          type: boolean
        deletedBy:
          type: string
          description: ID of user who deleted this user
        profilePicture:
          type: string
          nullable: true
          description: Base64-encoded data URI of the user's display picture
        slug:
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string
        __v:
          type: integer
      required:
      - _id
      - orgId
      - email
      - fullName
      - hasLoggedIn
      - isDeleted
      - slug
      - createdAt
      - updatedAt
      - __v
    OrgAuthConfigCreateRequest:
      type: object
      additionalProperties: false
      description: Request to create initial organization auth configuration
      properties:
        contactEmail:
          type: string
          format: email
          description: Organization contact email
        registeredName:
          type: string
          description: Organization registered name
        adminFullName:
          type: string
          description: Admin user full name
        sendEmail:
          type: boolean
          description: Whether to send welcome email
          default: false
      required:
      - contactEmail
      - registeredName
      - adminFullName
    ToolApprovalAnswer:
      type: object
      description: |
        The person's answer to a tool approval card. The web app sends it with the query
        `Tool approval: allow` or `Tool approval: deny`, and the request carries on the turn that
        stopped on the card: the saved call runs (when allowed) and its result answers the call
        the model made, in the same reply. The call is the one saved server-side when the card was
        shown (answerable for 15 minutes, settled once, bound to the asking user and
        conversation); only its id and the answer travel here. A reply that answered a card
        can't be regenerated.
      required:
      - approvalId
      - decision
      properties:
        approvalId:
          type: string
          maxLength: 64
        decision:
          type: string
          enum:
          - allow
          - deny
        remember:
          type: boolean
          description: |
            "Don't ask again for this tool": the answer becomes the person's own rule for the
            tool (Pre-approved for allow, Deny for deny).
    ErrorResponse:
      type: object
      additionalProperties: false
      description: |
        Standard error envelope returned by all errors routed through `ErrorMiddleware`.
        Applies to all `BaseError` subclasses including `HttpError`, `ValidationError`, and others.
        The `code` field is a machine-readable string identifying the error type (e.g.
        `HTTP_UNAUTHORIZED`, `HTTP_NOT_FOUND`, `VALIDATION_ERROR`, `INTERNAL_ERROR`).
      properties:
        error:
          type: object
          additionalProperties: false
          required:
          - code
          - message
          properties:
            requestId:
              type: string
              description: |
                Identifier for this request, echoed so a bug report can quote it.
                Absent when the request never reached the middleware that assigns one.
            code:
              type: string
              description: |
                Machine-readable error code. For application errors it takes the form `HTTP_<VARIANT>`
                For unhandled runtime errors (e.g. database unavailable) it is `INTERNAL_ERROR`.
              example: HTTP_FORBIDDEN
            message:
              type: string
              description: Human-readable description of the error
              example: You need admin access to do this. Ask an admin in your organisation.
            metadata:
              type: object
              description: Additional context (only present in development environments)
              additionalProperties: true
      required:
      - error
    StreamRecordErrorResponse:
      type: object
      additionalProperties: false
      description: |
        Error payload returned by the legacy record-stream proxy when the downstream
        streaming request fails after route middleware has passed.
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message from the gateway or downstream stream service
    KnowledgeLimit:
      type: object
      additionalProperties: false
      description: |
        What a connected app may see: an OAuth app's limit is picked by its
        creator and holds for every user who connects it; a personal access
        token's by its owner. Search, chat, agent chat and every record read by
        id stay inside it, and inside the connecting user's own permissions.
        Omit it for everything the user can see. Sent, it must name at least one id and at
        most 50 in all, since it is signed into every token the app gets.
      properties:
        apps:
          type: array
          items:
            type: string
            format: uuid
          description: Whole connectors and collections.
        recordGroups:
          type: array
          items:
            type: string
            format: uuid
          description: Record groups (a drive, space or project), with the groups nested in them.
        records:
          type: array
          items:
            type: string
            format: uuid
          description: Folders or records, with everything under them.
    OAuthTokenRequest:
      type: object
      description: |
        OAuth 2.0 Token Request (RFC 6749 Section 4.1.3).
        Request body for exchanging authorization code or credentials for tokens.
      properties:
        grant_type:
          type: string
          enum:
          - authorization_code
          - client_credentials
          - refresh_token
          - urn:ietf:params:oauth:grant-type:device_code
          - urn:ietf:params:oauth:grant-type:token-exchange
          description: |
            OAuth grant type:
            - `authorization_code`: Exchange auth code for tokens
            - `client_credentials`: Machine-to-machine auth
            - `refresh_token`: Get new access token using refresh token
            - `urn:ietf:params:oauth:grant-type:device_code`: Poll for the tokens of a device
              authorization (RFC 8628) started with `POST /oauth2/device_authorization`
            - `urn:ietf:params:oauth:grant-type:token-exchange`: Service-account
              delegation (RFC 8693). Exchanges a service token for a
              short-lived token that acts as one named person. Enterprise
              edition; kept in this enum because the request shape is the same
              wherever the grant is offered.
        code:
          type: string
          description: Authorization code (required for authorization_code grant)
        redirect_uri:
          type: string
          format: uri
          description: Redirect URI (required for authorization_code grant)
        device_code:
          type: string
          minLength: 1
          description: |
            The `device_code` from `POST /oauth2/device_authorization` (required for the device_code
            grant; without it the answer is `400 invalid_grant`)
        client_id:
          type: string
          minLength: 1
          description: Client ID (can also be sent via Basic auth header, which then takes precedence)
        client_secret:
          type: string
          description: Client secret (can also be sent via Basic auth header)
        refresh_token:
          type: string
          description: Refresh token (required for refresh_token grant)
        scope:
          type: string
          description: Requested scopes (optional, defaults to original grant scopes)
        code_verifier:
          type: string
          description: |
            PKCE code verifier (RFC 7636). Required if code_challenge was used.
            Must be 43-128 characters from [A-Za-z0-9-._~]
          pattern: ^[A-Za-z0-9\-._~]{43,128}$
        subject_token:
          type: string
          minLength: 1
          maxLength: 8192
          description: |
            The service token being exchanged (token-exchange grant only).
            This is the only authentication the grant has: no `client_id` or
            `client_secret` is sent, because the service token already carries
            a verified identity and the scopes that bound it.
        subject_token_type:
          type: string
          maxLength: 128
          description: |
            Optional. Must be `urn:ietf:params:oauth:token-type:access_token`
            when sent (token-exchange grant only).
        requested_subject:
          type: string
          minLength: 1
          maxLength: 320
          description: |
            The person to act as, by user id or email address (token-exchange
            grant only). Must be on the service account's allow-list, and must
            not be an administrator.
      required:
      - grant_type
    OAuthTokenResponse:
      type: object
      description: |
        OAuth 2.0 Token Response (RFC 6749 Section 5.1).
        Contains the access token and optional refresh/ID tokens.
      properties:
        access_token:
          type: string
          description: The access token for API requests
        token_type:
          type: string
          example: Bearer
          description: Token type (always "Bearer")
        expires_in:
          type: integer
          description: Access token lifetime in seconds
          example: 3600
        refresh_token:
          type: string
          description: |
            Refresh token for obtaining new access tokens. Issued only when the token acts as a user
            (`authorization_code`, `refresh_token` and `device_code` grants) and the granted scopes
            include `offline_access`; never for `client_credentials`.
        scope:
          type: string
          description: |
            Granted scopes, space-separated (may differ from requested). Empty for a
            `client_credentials` token whose app holds only user-bound scopes (`openid`, `profile`,
            `email`, `offline_access`), which are dropped from that grant.
        issued_token_type:
          type: string
          description: |
            The type of the issued token (RFC 8693 Section 2.2.1). Returned by
            the token-exchange grant, where it is always
            `urn:ietf:params:oauth:token-type:access_token`.
          example: urn:ietf:params:oauth:token-type:access_token
    OAuthRevokeRequest:
      type: object
      description: |
        OAuth 2.0 Token Revocation Request (RFC 7009).
        Revokes an access or refresh token.
      properties:
        token:
          type: string
          minLength: 1
          description: The token to revoke
        token_type_hint:
          type: string
          enum:
          - access_token
          - refresh_token
          description: Hint about token type (optional, improves performance)
        client_id:
          type: string
          minLength: 1
          description: Client ID
        client_secret:
          type: string
          description: |
            Client secret. Required for a confidential client (missing or empty: `401 invalid_client`);
            a public client, such as the first-party device app, is identified by `client_id` alone. A
            wrong secret is `401 invalid_client`.
      required:
      - token
      - client_id
    OAuthIntrospectRequest:
      type: object
      description: |
        OAuth 2.0 Token Introspection Request (RFC 7662).
        Check if a token is active and get its metadata.
      properties:
        token:
          type: string
          minLength: 1
          description: The token to introspect
        token_type_hint:
          type: string
          enum:
          - access_token
          - refresh_token
          description: Hint about token type
        client_id:
          type: string
          minLength: 1
          description: Client ID
        client_secret:
          type: string
          description: |
            Client secret. Not checked by the validator, but client authentication cannot succeed
            without it: when it is missing the route answers `{active: false}` even for a live token, for public and confidential clients
            alike. A wrong secret is `401 invalid_client`.
      required:
      - token
      - client_id
    OAuthIntrospectResponse:
      type: object
      description: |
        OAuth 2.0 Token Introspection Response (RFC 7662).
        Contains token metadata if active, or just `active: false` if not.
      properties:
        active:
          type: boolean
          description: Whether the token is currently active
        scope:
          type: string
          description: Scopes granted to the token
        client_id:
          type: string
          description: Client ID the token was issued to
        username:
          type: string
          description: User identifier (if user-based token)
        token_type:
          type: string
          description: Token type
        exp:
          type: integer
          description: Token expiration timestamp (Unix epoch)
        iat:
          type: integer
          description: Token issuance timestamp (Unix epoch)
        nbf:
          type: integer
          description: Token not-before timestamp (Unix epoch)
        user_id:
          type: string
          description: User ID
        aud:
          type: string
          description: Audience (client ID)
        iss:
          type: string
          description: Issuer URL
        jti:
          type: string
          description: Unique token identifier
      required:
      - active
    OAuthErrorResponse:
      type: object
      description: |
        OAuth 2.0 Error Response (RFC 6749 Section 5.2).
        Standard error format for OAuth endpoints.
      properties:
        error:
          type: string
          description: |
            Error code. Common values:
            - `invalid_request` - Missing or invalid parameter
            - `invalid_client` - Client authentication failed
            - `invalid_grant` - Invalid authorization code or refresh token
            - `unauthorized_client` - Client not authorized for this grant type
            - `unsupported_grant_type` - Grant type not supported
            - `invalid_scope` - Requested scope is invalid or exceeds allowed
            - `access_denied` - User denied authorization
            - `invalid_target` - The requested subject cannot be acted as
              (RFC 8693). Returned by the token-exchange grant for every
              refusal about the person asked for, with one wording, so a
              service token cannot tell "no such person" from "not on your
              list". The real cause is in the delegation log.
          enum:
          - invalid_request
          - invalid_client
          - invalid_grant
          - invalid_target
          - unauthorized_client
          - unsupported_grant_type
          - invalid_scope
          - access_denied
          - server_error
          - authorization_pending
          - slow_down
          - expired_token
        error_description:
          type: string
          description: Human-readable error description
        error_uri:
          type: string
          format: uri
          description: URI with more information about the error
        state:
          type: string
          description: State parameter from the authorization request
      required:
      - error
    OAuthUserInfoResponse:
      type: object
      description: |
        OpenID Connect UserInfo Response.
        Contains claims about the authenticated user.
      properties:
        user_id:
          type: string
          description: User ID
        name:
          type: string
          description: Full name
        given_name:
          type: string
          description: First name
        family_name:
          type: string
          description: Last name
        email:
          type: string
          format: email
          description: Email address
        email_verified:
          type: boolean
          description: Whether email has been verified
        picture:
          type: string
          format: uri
          description: Profile picture URL
        updated_at:
          type: integer
          description: Last profile update timestamp (Unix epoch)
      required:
      - user_id
    CreateOAuthAppRequest:
      type: object
      description: |
        Request to create a new OAuth app (`createAppSchema` in `oauth.validators.ts`).

        **Required:** `name`, `allowedScopes`. **Optional:** `description`, `redirectUris`, `allowedGrantTypes`,
        `homepageUrl`, `privacyPolicyUrl`, `termsOfServiceUrl`, `isConfidential`, `accessTokenLifetime`,
        `refreshTokenLifetime`, `tokenIdentityUserId`.

        **Redirect rule (Zod refine):** If the effective grant list includes `authorization_code`
        (including when `allowedGrantTypes` is omitted — defaults to `authorization_code` + `refresh_token`),
        at least one redirect URI is required. If grants exclude `authorization_code`, `redirectUris` may be omitted.

        **Service account rule:** If the effective grant list includes `client_credentials`,
        `tokenIdentityUserId` is **required** and the caller must be an organisation administrator.
        That grant issues tokens with no person in them, so without a service account the app would act
        as whoever created it. Omitting it answers `400`; a non-administrator answers `403`.
      properties:
        name:
          type: string
          description: App name (displayed to users during authorization)
          minLength: 1
          maxLength: 100
          example: My Integration App
        tokenIdentityUserId:
          type: string
          description: |
            The service account this app's own tokens act as. Required when
            `allowedGrantTypes` includes `client_credentials`, ignored otherwise.

            Must name a service account in the same organisation that is not disabled;
            an ordinary user's id is refused. Administrators only.
          example: 65f0c0ffee00000000000000
        description:
          type: string
          description: App description
          maxLength: 500
          example: Integrates PipesHub with our internal tools
        redirectUris:
          type: array
          items:
            type: string
            format: uri
            pattern: ^(?:cursor://anysphere\.cursor-mcp/oauth/callback|[\x00-\x20]*(?:[Hh][Tt][Tt][Pp][Ss]:[/\\]*[^/\\?#\x00-\x20][^#]*#?|[A-Za-z][A-Za-z0-9+.-]*://(?:[^/?#@]*@)?(?:[Ll][Oo][Cc][Aa][Ll][Hh][Oo][Ss][Tt]|127\.0\.0\.1)(?::[0-9]*)?(?:[/?][^#]*)?#?)[\x00-\x20]*)$
          description: |
            Allowed redirect URIs (max 10). Required when an effective grant list includes `authorization_code`
            (including the default when `allowedGrantTypes` is omitted).
            Each URI must parse as a URL (`VALIDATION_ERROR` otherwise), and the service then refuses with
            `400 OAUTH_INVALID_REDIRECT_URI` any URI that is not `https:` and whose host is not `localhost` or
            `127.0.0.1` (any scheme is let through on those two hosts), or that carries a fragment.
            The one exception is the literal `cursor://anysphere.cursor-mcp/oauth/callback`.
            Both checks use WHATWG `new URL()`, so the scheme and a `localhost` host match in any case,
            `https:` may be followed by any number of `/` or `\` (or none), and surrounding whitespace is
            allowed and trimmed before the URI is stored; the URI is otherwise stored as sent. `https://`
            with no host does not parse. The pattern approximates these rules.
          maxItems: 10
          example:
          - https://myapp.com/callback
          - http://localhost:3000/callback
        allowedGrantTypes:
          type: array
          items:
            type: string
            enum:
            - authorization_code
            - client_credentials
            - refresh_token
          description: |
            Allowed grant types. Defaults to `["authorization_code", "refresh_token"]` if omitted (applied by the service, not Zod).
          example:
          - authorization_code
          - refresh_token
        allowedScopes:
          type: array
          items:
            type: string
          description: Scopes the app can request (non-empty)
          minItems: 1
          example:
          - openid
          - profile
          - read:records
        homepageUrl:
          type: string
          format: uri
          pattern: '^[A-Za-z][A-Za-z0-9+.-]*:'
          description: App homepage URL (shown during authorization). Must parse as a URL (`z.string().url()`); the pattern is the closest JSON Schema can say.
        privacyPolicyUrl:
          type: string
          format: uri
          pattern: '^[A-Za-z][A-Za-z0-9+.-]*:'
          description: Privacy policy URL. Must parse as a URL (`z.string().url()`); the pattern is the closest JSON Schema can say.
        termsOfServiceUrl:
          type: string
          format: uri
          pattern: '^[A-Za-z][A-Za-z0-9+.-]*:'
          description: Terms of service URL. Must parse as a URL (`z.string().url()`); the pattern is the closest JSON Schema can say.
        isConfidential:
          type: boolean
          description: |
            Whether the app can securely store secrets.
            - `true`: Server-side app (secret required for token requests)
            - `false`: Browser/mobile app (must use PKCE)
          default: true
        accessTokenLifetime:
          type: integer
          description: Access token lifetime in seconds (300–86400)
          minimum: 300
          maximum: 86400
          default: 3600
          example: 3600
        refreshTokenLifetime:
          type: integer
          description: Refresh token lifetime in seconds (3600–31536000)
          minimum: 3600
          maximum: 31536000
          default: 2592000
          example: 2592000
        knowledgeLimit:
          $ref: '#/components/schemas/KnowledgeLimit'
      required:
      - name
      - allowedScopes
    UpdateOAuthAppRequest:
      type: object
      description: |
        Request to update an OAuth app (`updateAppSchema` in `oauth.validators.ts`).

        All fields are optional — include only fields that should change. URL fields (`homepageUrl`, `privacyPolicyUrl`, `termsOfServiceUrl`) accept `null` to clear them (nullable in Zod).

        **Redirect rule (Zod refine):** If `allowedGrantTypes` includes `authorization_code` and `redirectUris` is present in the body, `redirectUris` must contain at least one URI.
      properties:
        name:
          type: string
          description: App name
          minLength: 1
          maxLength: 100
        description:
          type: string
          description: App description
          maxLength: 500
        redirectUris:
          type: array
          items:
            type: string
            format: uri
            pattern: ^(?:cursor://anysphere\.cursor-mcp/oauth/callback|[\x00-\x20]*(?:[Hh][Tt][Tt][Pp][Ss]:[/\\]*[^/\\?#\x00-\x20][^#]*#?|[A-Za-z][A-Za-z0-9+.-]*://(?:[^/?#@]*@)?(?:[Ll][Oo][Cc][Aa][Ll][Hh][Oo][Ss][Tt]|127\.0\.0\.1)(?::[0-9]*)?(?:[/?][^#]*)?#?)[\x00-\x20]*)$
          description: |
            Allowed redirect URIs (up to 10). Required when `authorization_code` grant type is enabled.
            Preserved in the database even if `authorization_code` is removed from grant types.
            Each URI must parse as a URL (`VALIDATION_ERROR` otherwise), and the service then refuses with
            `400 OAUTH_INVALID_REDIRECT_URI` any URI that is not `https:` and whose host is not `localhost` or
            `127.0.0.1` (any scheme is let through on those two hosts), or that carries a fragment.
            The one exception is the literal `cursor://anysphere.cursor-mcp/oauth/callback`.
            Both checks use WHATWG `new URL()`, so the scheme and a `localhost` host match in any case,
            `https:` may be followed by any number of `/` or `\` (or none), and surrounding whitespace is
            allowed and trimmed before the URI is stored; the URI is otherwise stored as sent. `https://`
            with no host does not parse. The pattern approximates these rules.
          maxItems: 10
        allowedGrantTypes:
          type: array
          items:
            type: string
            enum:
            - authorization_code
            - client_credentials
            - refresh_token
        allowedScopes:
          type: array
          items:
            type: string
          minItems: 1
        homepageUrl:
          type: string
          format: uri
          pattern: '^[A-Za-z][A-Za-z0-9+.-]*:'
          nullable: true
          description: '`null` clears it. Must parse as a URL (`z.string().url()`); the pattern is the closest JSON Schema can say.'
        privacyPolicyUrl:
          type: string
          format: uri
          pattern: '^[A-Za-z][A-Za-z0-9+.-]*:'
          nullable: true
          description: '`null` clears it. Must parse as a URL (`z.string().url()`); the pattern is the closest JSON Schema can say.'
        termsOfServiceUrl:
          type: string
          format: uri
          pattern: '^[A-Za-z][A-Za-z0-9+.-]*:'
          nullable: true
          description: '`null` clears it. Must parse as a URL (`z.string().url()`); the pattern is the closest JSON Schema can say.'
        accessTokenLifetime:
          type: integer
          minimum: 300
          maximum: 86400
        refreshTokenLifetime:
          type: integer
          minimum: 3600
          maximum: 31536000
        knowledgeLimit:
          description: |
            `null` lifts the limit. A change that takes anything away revokes
            the app's outstanding tokens, so users connect again. A change
            that only adds (a lift included) keeps them: each token, and each
            refresh of it, stays at the limit its user agreed to, and the new
            items reach a user once they connect again.
          nullable: true
          allOf:
          - $ref: '#/components/schemas/KnowledgeLimit'
    OAuthAppResponse:
      type: object
      description: |
        OAuth app details (without secret). Fields under `required:` always appear
        in `toAppResponse` (`oauth.app.service.ts`); optional URL/description fields
        are only present when set by the caller.
      required:
      - id
      - slug
      - clientId
      - name
      - redirectUris
      - allowedGrantTypes
      - allowedScopes
      - status
      - isConfidential
      - accessTokenLifetime
      - refreshTokenLifetime
      - createdAt
      - updatedAt
      properties:
        id:
          type: string
          description: App ID
        slug:
          type: string
          description: URL-friendly app slug
        clientId:
          type: string
          description: OAuth client ID
        name:
          type: string
          description: App name
        description:
          type: string
          description: App description
        redirectUris:
          type: array
          items:
            type: string
            format: uri
          description: Allowed redirect URIs (always returned; may be empty)
        allowedGrantTypes:
          type: array
          items:
            type: string
          description: Allowed grant types
        allowedScopes:
          type: array
          items:
            type: string
          description: Allowed scopes
        status:
          type: string
          enum:
          - active
          - suspended
          - revoked
          description: App status
        homepageUrl:
          type: string
          format: uri
          description: App homepage
        privacyPolicyUrl:
          type: string
          format: uri
          description: Privacy policy URL
        termsOfServiceUrl:
          type: string
          format: uri
          description: Terms of service URL
        isConfidential:
          type: boolean
          description: Whether app is a confidential client
        accessTokenLifetime:
          type: integer
          description: Access token lifetime in seconds
        refreshTokenLifetime:
          type: integer
          description: Refresh token lifetime in seconds
        knowledgeLimit:
          $ref: '#/components/schemas/KnowledgeLimit'
        tokenIdentityUserId:
          type: string
          description: |
            The service account this app's own `client_credentials` tokens act as.

            Absent means the app has no service account and its tokens act as whoever
            created it. Apps registered since a service account became required always
            have one; an older app may not, and those are the ones an administrator
            still has to move.
          example: 65f0c0ffee00000000000000
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp
    OAuthAppWithSecret:
      allOf:
      - $ref: '#/components/schemas/OAuthAppResponse'
      - type: object
        properties:
          clientSecret:
            type: string
            description: |
              Client secret (only shown on creation and secret regeneration).
              Store this securely - it cannot be retrieved later.
        required:
        - clientSecret
    CreateOAuthAppResponse:
      type: object
      description: |
        Response body for `POST /oauth-clients` (`oauth.app.controller.ts` `createApp`).
        The new app (including one-time `clientSecret`) is nested under `app`.
      required:
      - message
      - app
      properties:
        message:
          type: string
          example: OAuth app created successfully
        app:
          $ref: '#/components/schemas/OAuthAppWithSecret'
    RegenerateOAuthAppSecretResponse:
      type: object
      description: |
        Response body for `POST /oauth-clients/{appId}/regenerate-secret` (`regenerateSecret`).
      required:
      - message
      - clientId
      - clientSecret
      properties:
        message:
          type: string
          example: Client secret regenerated successfully
        clientId:
          type: string
          description: OAuth client ID (unchanged)
        clientSecret:
          type: string
          description: New client secret (store securely; previous secret is invalidated)
    UpdateOAuthAppResponse:
      type: object
      description: |
        Response body for `PUT /oauth-clients/{appId}` (`oauth.app.controller.ts` `updateApp`).
        Updated app (never includes `clientSecret`) is nested under `app`.
      required:
      - message
      - app
      properties:
        message:
          type: string
          example: OAuth app updated successfully
        app:
          $ref: '#/components/schemas/OAuthAppResponse'
    SuspendOAuthAppResponse:
      type: object
      description: |
        Response body for `POST /oauth-clients/{appId}/suspend`
        (`oauth.app.controller.ts` `suspendApp`). Suspended app (never includes
        `clientSecret`) is nested under `app`.
      required:
      - message
      - app
      properties:
        message:
          type: string
          example: OAuth app suspended successfully
        app:
          $ref: '#/components/schemas/OAuthAppResponse'
    ActivateOAuthAppResponse:
      type: object
      description: |
        Response body for `POST /oauth-clients/{appId}/activate`
        (`oauth.app.controller.ts` `activateApp`). Re-activated app (never includes
        `clientSecret`) is nested under `app`.
      required:
      - message
      - app
      properties:
        message:
          type: string
          example: OAuth app activated successfully
        app:
          $ref: '#/components/schemas/OAuthAppResponse'
    OAuthAppListResponse:
      type: object
      description: Paginated list of OAuth apps
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OAuthAppResponse'
          description: List of OAuth apps
        pagination:
          type: object
          required:
          - page
          - limit
          - total
          - totalPages
          properties:
            page:
              type: integer
              description: Current page number
            limit:
              type: integer
              description: Items per page
            total:
              type: integer
              description: Total number of items
            totalPages:
              type: integer
              description: Total number of pages
    OAuthScopeInfo:
      type: object
      description: Information about an OAuth scope
      properties:
        name:
          type: string
          description: Scope identifier
          example: openid
        description:
          type: string
          description: Human-readable scope description
          example: OpenID Connect authentication
        category:
          type: string
          description: Scope category for grouping (matches the key under `scopes` on list responses)
          example: Identity
        requiresUserConsent:
          type: boolean
          description: Whether end-user consent is required when this scope is requested
          example: false
      required:
      - name
      - description
      - category
      - requiresUserConsent
    OAuthScopesGroupedResponse:
      type: object
      description: |
        OAuth scopes available to the signed-in user for app registration, grouped by category label.
        Category keys are UI labels (e.g. `Identity`, `Knowledge Base`); each maps to a list of scopes in that group.
        Categories defined in server config may appear with an **empty array** when every scope in that category is restricted for the caller's role (e.g. non–org-admin users never receive admin-only scopes).
      properties:
        scopes:
          type: object
          description: Map of category display name to scopes in that category
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/OAuthScopeInfo'
      required:
      - scopes
    OAuthClientManagementRateLimitError:
      type: object
      description: JSON body when OAuth client management routes exceed the per-minute rate limit (same limiter as other `/oauth-clients/*` routes).
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              example: TOO_MANY_REQUESTS
            message:
              type: string
              example: Too many OAuth client requests. Please try again later.
            retryAfter:
              type: integer
              nullable: true
              description: Seconds until the limit window resets (when `Retry-After` is present); may be null.
    ApplicationJsonErrorResponse:
      type: object
      description: |
        Standard JSON error envelope from `ErrorMiddleware` for `BaseError` subclasses (`error.middleware.ts`).
        Returned for most API 4xx errors (unauthorized, forbidden, not found, validation failures, etc.).
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            requestId:
              type: string
              description: |
                Identifier for this request, echoed so a bug report can quote it.
                Absent when the request never reached the middleware that assigns one.
            code:
              type: string
              description: Machine-readable code (e.g. `HTTP_UNAUTHORIZED`, `HTTP_FORBIDDEN`).
            message:
              type: string
            metadata:
              type: object
              description: Optional; may appear in non-production for some errors.
              additionalProperties: true
    RateLimitErrorResponse:
      type: object
      description: Rate-limit error payload (shape differs from standard error responses).
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Error code.
            message:
              type: string
            retryAfter:
              type: integer
              nullable: true
              description: Suggested seconds to wait before retrying.
      required:
      - error
    OAuthTokenListItem:
      type: object
      description: |
        Information about an issued token (one element returned by `listTokensForApp`
        in `oauth_token.service.ts`). `userId` is omitted for client-credentials access
        tokens; all other fields are always populated.
      required:
      - id
      - tokenType
      - scopes
      - createdAt
      - expiresAt
      - isRevoked
      properties:
        id:
          type: string
          description: Token ID
        tokenType:
          type: string
          enum:
          - access
          - refresh
          description: Type of token
        userId:
          type: string
          description: User ID (omitted for client-credentials access tokens)
        scopes:
          type: array
          items:
            type: string
          description: Granted scopes
        createdAt:
          type: string
          format: date-time
          description: Token creation time
        expiresAt:
          type: string
          format: date-time
          description: Token expiration time
        isRevoked:
          type: boolean
          description: Whether token has been revoked
    OAuthAppTokensListResponse:
      type: object
      description: |
        Response body for `GET /oauth-clients/{appId}/tokens` (`listAppTokens`).
      required:
      - tokens
      properties:
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/OAuthTokenListItem'
          description: Active access and refresh tokens for the app
    CreatePatRequest:
      type: object
      description: |
        Request to create a personal access token (`createPatTokenSchema` in `pat.validators.ts`).
        Fields not listed here are stripped by the validator and ignored.
      required:
      - name
      properties:
        name:
          type: string
          description: Label to help you recognize the token later
          minLength: 1
          maxLength: 100
          example: Claude Desktop
        scopes:
          type: array
          items:
            type: string
          minItems: 1
          description: |
            Scopes to grant, validated against the org's configured `MCP_SCOPES`
            (not the full role-aware OAuth-app scope set). Defaults to every
            scope in `MCP_SCOPES` if omitted.
          example:
          - kb:read
          - semantic:write
          maxItems: 100
        expiryDays:
          oneOf:
          - type: integer
            enum:
            - 30
            - 90
            - 365
          - type: string
            enum:
            - never
          description: |
            Token lifetime. Defaults to `30` if omitted — a token minted
            without an explicit choice shouldn't default to the longest
            lifetime. `"never"` is stored as a ~100-year expiry (the
            underlying schema field is required and TTL-indexed, so there's
            no literal null option). Any other value, including `null` and the
            string `"30"`, is a `400` validation error.
          default: 30
          example: 30
        knowledgeLimit:
          $ref: '#/components/schemas/KnowledgeLimit'
    PatListItem:
      type: object
      description: |
        A personal access token as seen by its own creator (one element of
        `GET /personal-access-tokens`'s `tokens` array, or the `token` object
        returned by `POST /personal-access-tokens` before `accessToken` is added).
      required:
      - id
      - name
      - scopes
      - createdAt
      - expiresAt
      properties:
        id:
          type: string
          description: Token ID
        name:
          type: string
          description: Token name
        scopes:
          type: array
          items:
            type: string
          description: Granted scopes
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          description: |
            Expiry timestamp. A `"never"`-expiry token is stored as a
            ~100-year-out date, not a literal null — treat anything decades
            out as "never" rather than a real deadline.
        lastUsedAt:
          type: string
          format: date-time
          description: |
            Last time this token successfully authenticated a request.
            Throttled server-side to update at most once per 5 minutes per
            token; absent if the token has never been used.
        knowledgeLimit:
          $ref: '#/components/schemas/KnowledgeLimit'
    PatWithSecret:
      allOf:
      - $ref: '#/components/schemas/PatListItem'
      - type: object
        required:
        - accessToken
        properties:
          accessToken:
            type: string
            description: |
              The raw token, `phpat_`-prefixed. Returned **only** in this
              creation response — only its hash is stored server-side, so
              it cannot be retrieved again later.
            example: phpat_eyJhbGciOiJIUzI1NiIs...
    CreatePatResponse:
      type: object
      description: Response body for `POST /personal-access-tokens` (`pat.controller.ts` `createToken`).
      required:
      - message
      - token
      properties:
        message:
          type: string
          example: Personal access token created successfully
        token:
          $ref: '#/components/schemas/PatWithSecret'
    ListPatResponse:
      type: object
      description: |
        Response body for `GET /personal-access-tokens` (`listTokens`) — the
        caller's own active tokens, capped at 100 most-recent server-side.
        Unlike the admin list, this is a flat array with no pagination
        envelope and no owner fields (it's implicitly scoped to the caller).
      required:
      - tokens
      properties:
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/PatListItem'
    RevokePatRequest:
      type: object
      description: |
        Optional request body for `DELETE /personal-access-tokens/{tokenId}`
        and `DELETE /personal-access-tokens/admin/{tokenId}`. The body itself
        is optional; `reason`, if present, is stored on the revocation for
        auditing.
      properties:
        reason:
          type: string
          description: |
            Stored on the revocation for auditing. There is no body validator:
            a `reason` that is not a string is ignored rather than refused, and
            the revocation goes ahead with the default reason.
          example: rotated
    RevokePatResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: Personal access token revoked successfully
    PatScopesListResponse:
      type: object
      description: |
        Response body for `GET /personal-access-tokens/scopes` (`listScopes`).
        Unlike `GET /oauth-clients/scopes`, this is a **flat array**, not
        grouped by category, and reflects the org's configured `MCP_SCOPES`
        rather than the full role-aware OAuth-app scope catalog.
      required:
      - scopes
      properties:
        scopes:
          type: array
          items:
            $ref: '#/components/schemas/OAuthScopeInfo'
    AdminPatListItem:
      description: |
        A personal access token as seen by an org admin — extends
        `PatListItem` with who it belongs to, since an admin is looking
        across every member's tokens rather than just their own.
      allOf:
      - $ref: '#/components/schemas/PatListItem'
      - type: object
        required:
        - userId
        - ownerDeleted
        properties:
          userId:
            type: string
            description: ID of the user who created this token
          ownerEmail:
            type: string
            format: email
            description: |
              Owner's email. Populated even when `ownerDeleted` is true
              (last-known value), for auditing.
          ownerFullName:
            type: string
            description: Owner's full name (same last-known-value behavior as `ownerEmail`)
          ownerDeleted:
            type: boolean
            description: |
              True if the owning user has been removed from the org (or no
              longer resolves at all). The token still appears — a deleted
              user's tokens stop authenticating automatically, but stay
              visible here so an admin can audit/clean them up.
    AdminPatListResponse:
      type: object
      description: |
        Response body for `GET /personal-access-tokens/admin` (`adminListTokens`).
        Paginated — unlike the self-service `ListPatResponse` — since an org
        can have far more active tokens than a fixed-window cap's worth.
      required:
      - data
      - pagination
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AdminPatListItem'
        pagination:
          type: object
          required:
          - page
          - limit
          - total
          - totalPages
          properties:
            page:
              type: integer
            limit:
              type: integer
              description: Items per page (max 100)
            total:
              type: integer
            totalPages:
              type: integer
    Address:
      type: object
      additionalProperties: false
      properties:
        _id:
          type: string
          format: ObjectId
          description: Optional address document id
        addressLine1:
          type: string
          description: Address line 1
        city:
          type: string
          description: City
        state:
          type: string
          description: State/Province
        postCode:
          type: string
          description: Postal/ZIP code
        country:
          type: string
          description: Country
    Organization:
      type: object
      properties:
        _id:
          type: string
          format: ObjectId
          description: Unique organization identifier
        slug:
          type: string
          description: Unique slug for the organization
        registeredName:
          type: string
          description: Registered name
        shortName:
          type: string
          description: Short name or display name
        domain:
          type: string
          description: Organization domain
        contactEmail:
          type: string
          format: email
          description: Contact email address
        accountType:
          type: string
          enum:
          - individual
          - business
          description: Type of account
        permanentAddress:
          $ref: '#/components/schemas/Address'
        onBoardingStatus:
          type: string
          enum:
          - configured
          - notConfigured
          - skipped
          description: Onboarding status
        isDeleted:
          type: boolean
          description: Soft delete flag
          default: false
        __v:
          type: integer
          description: Document version (MongoDB)
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp (ISO 8601)
        signupChannel:
          type: string
          description: 'Where the signup came from: the `ref` tag it was made with, or `direct`. Absent on organizations created before it was recorded.'
        signupReferrerDomain:
          type: string
          description: For a `direct` signup, the referring site's domain, when there was one.
      required:
      - _id
      - slug
      - registeredName
      - domain
      - contactEmail
      - accountType
      - onBoardingStatus
      - isDeleted
      - createdAt
      - updatedAt
      - __v
    KnowledgeBaseCreateResponse:
      type: object
      additionalProperties: false
      description: Response returned when a knowledge base is created
      properties:
        id:
          type: string
          description: Knowledge base ID
        name:
          type: string
          description: Knowledge base name
        createdAtTimestamp:
          type: integer
          format: int64
          description: Creation timestamp in milliseconds
        updatedAtTimestamp:
          type: integer
          format: int64
          description: Last update timestamp in milliseconds
        userRole:
          type: string
          enum:
          - OWNER
          - WRITER
          - READER
          description: User's role in this knowledge base
      required:
      - id
      - name
      - createdAtTimestamp
      - updatedAtTimestamp
      - userRole
    FolderCreateResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned when a folder is created (root or nested subfolder)
      properties:
        id:
          type: string
          description: Unique folder identifier
        name:
          type: string
          description: Name of the folder
      required:
      - id
      - name
    FolderUpdateResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned by PUT /knowledgeBase/{kbId}/folder/{folderId} (updateFolder).
      required:
      - success
      - message
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Folder updated successfully
    FolderDeleteResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned by DELETE /knowledgeBase/{kbId}/folder/{folderId} (deleteFolder).
      required:
      - success
      - message
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Folder deleted successfully
    KnowledgeBaseMoveRecordRequestBody:
      type: object
      description: Request body for PUT /knowledgeBase/{kbId}/record/{recordId}/move (moveRecord). Fields other than `newParentId` are dropped by the validator, not refused.
      required:
      - newParentId
      properties:
        newParentId:
          type: string
          nullable: true
          description: Target folder ID, or null to move the record to the knowledge base root
    KnowledgeBaseMoveRecordResponse:
      type: object
      additionalProperties: false
      description: Response returned by PUT /knowledgeBase/{kbId}/record/{recordId}/move (moveRecord).
      required:
      - success
      - message
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Record moved successfully
    GetAllKnowledgeBaseResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned by GET /knowledgeBase (listKnowledgeBases).
      required:
      - knowledgeBases
      - pagination
      - filters
      properties:
        knowledgeBases:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - id
            - name
            - connectorId
            - createdAtTimestamp
            - updatedAtTimestamp
            - createdBy
            - userRole
            - folders
            properties:
              id:
                type: string
              name:
                type: string
              connectorId:
                type: string
                nullable: true
              createdAtTimestamp:
                type: integer
                format: int64
              updatedAtTimestamp:
                type: integer
                format: int64
              createdBy:
                type: string
              userRole:
                type: string
                enum:
                - OWNER
                - WRITER
                - READER
              status:
                type: string
                nullable: true
                enum:
                - IDLE
                - QUEUED
                - SYNCING
                - FULL_SYNCING
                - DELETING
                description: |
                  The knowledge base's processing state. `DELETING` while it is being deleted (writes are
                  refused with 409). `IDLE`, `QUEUED`, `SYNCING` or `FULL_SYNCING` otherwise, or null on a
                  knowledge base that has not been processed yet.
              folders:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  required:
                  - id
                  - name
                  properties:
                    id:
                      type: string
                    name:
                      type: string
                    createdAtTimestamp:
                      type: integer
                      format: int64
                    path:
                      type: string
        pagination:
          type: object
          additionalProperties: false
          required:
          - page
          - limit
          - totalCount
          - totalPages
          - hasNext
          - hasPrev
          properties:
            page:
              type: integer
            limit:
              type: integer
            totalCount:
              type: integer
            totalPages:
              type: integer
            hasNext:
              type: boolean
            hasPrev:
              type: boolean
        filters:
          type: object
          additionalProperties: false
          required:
          - applied
          - available
          properties:
            applied:
              type: object
              additionalProperties: false
              description: |
                Active filters. Empty `{}` when defaults. Keys use snake_case for sort
                fields (backend convention in kb_service.py).
              properties:
                search:
                  type: string
                permissions:
                  type: array
                  items:
                    type: string
                    enum:
                    - OWNER
                    - WRITER
                    - READER
                sort_by:
                  type: string
                  enum:
                  - name
                  - createdAtTimestamp
                  - updatedAtTimestamp
                  - userRole
                sort_order:
                  type: string
                  enum:
                  - asc
                  - desc
            available:
              type: object
              additionalProperties: false
              required:
              - permissions
              - sortFields
              - sortOrders
              properties:
                permissions:
                  type: array
                  items:
                    type: string
                    enum:
                    - OWNER
                    - WRITER
                    - READER
                sortFields:
                  type: array
                  items:
                    type: string
                    enum:
                    - name
                    - createdAtTimestamp
                    - updatedAtTimestamp
                    - userRole
                sortOrders:
                  type: array
                  items:
                    type: string
                    enum:
                    - asc
                    - desc
    GetKnowledgeBaseById:
      type: object
      additionalProperties: false
      description: Response returned by GET /knowledgeBase/{kbId} (getKnowledgeBase).
      required:
      - id
      - name
      - connectorId
      - createdAtTimestamp
      - updatedAtTimestamp
      - createdBy
      - userRole
      - folders
      properties:
        id:
          type: string
          description: Knowledge base ID
        name:
          type: string
          description: Knowledge base name
        connectorId:
          type: string
          nullable: true
          description: Associated connector ID (null for manual KBs)
        createdAtTimestamp:
          type: integer
          format: int64
          description: Creation timestamp in milliseconds
        updatedAtTimestamp:
          type: integer
          format: int64
          description: Last update timestamp in milliseconds
        createdBy:
          type: string
          description: User ID of the creator
        userRole:
          type: string
          enum:
          - OWNER
          - WRITER
          - READER
          description: User's role in this knowledge base
        status:
          type: string
          nullable: true
          enum:
          - IDLE
          - QUEUED
          - SYNCING
          - FULL_SYNCING
          - DELETING
          description: |
            `DELETING` while the knowledge base is being deleted: reads work, every write is refused with 409
            (`error.code` `HTTP_KB_BEING_DELETED`), and deleting it again finishes the job. Otherwise its
            processing state (`IDLE`, `QUEUED`, `SYNCING`, `FULL_SYNCING`), or null before it is first processed.
        folders:
          type: array
          description: |
            Every folder in this knowledge base, nested ones included, with nothing that tells
            a nested folder from a root-level one (no parent id). Files are not listed. A
            folder moved to the trash is still listed.
          items:
            type: object
            additionalProperties: false
            required:
            - id
            - name
            properties:
              id:
                type: string
                description: Folder ID
              name:
                type: string
                description: Folder name
              createdAtTimestamp:
                type: integer
                format: int64
                description: Creation timestamp in milliseconds
    UpdateKnowledgeBaseById:
      type: object
      additionalProperties: false
      description: Response returned by PUT /knowledgeBase/{kbId} (updateKnowledgeBase).
      required:
      - success
      - message
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Knowledge base updated successfully
    DeleteKnowledgeBaseById:
      type: object
      additionalProperties: false
      description: Response returned by DELETE /knowledgeBase/{kbId} (deleteKnowledgeBase).
      required:
      - success
      - message
      properties:
        success:
          type: boolean
          example: true
        message:
          type: string
          example: Knowledge base deleted successfully
    RecordTypeEnum:
      type: string
      description: |
        Type of content. Mirrors the backend `RecordType` enum
        (`backend/python/app/models/entities.py`); connector-sourced records
        may use any of the connector-specific types below.
        - FILE: Uploaded or synced documents (PDF, DOCX, etc.)
        - DRIVE: Drive/folder container (Google Drive, OneDrive, etc.)
        - WEBPAGE: Web pages crawled or bookmarked
        - DATABASE: Database object (e.g. Notion database)
        - DATASOURCE: Data source object
        - MESSAGE: Chat/messaging content (Slack, Teams)
        - MAIL: Email messages (Gmail, Outlook)
        - GROUP_MAIL: Group/shared mailbox email messages
        - TICKET: Support/issue tickets (Jira, ServiceNow)
        - COMMENT: Comments from collaboration tools
        - INLINE_COMMENT: Inline comments anchored to content (e.g. Confluence)
        - CONFLUENCE_PAGE: Confluence page
        - CONFLUENCE_BLOGPOST: Confluence blog post
        - SHAREPOINT_PAGE: SharePoint page
        - SHAREPOINT_LIST: SharePoint list
        - SHAREPOINT_LIST_ITEM: SharePoint list item
        - SHAREPOINT_DOCUMENT_LIBRARY: SharePoint document library
        - LINK: Web link / bookmark
        - PROJECT: Project entity (e.g. Jira project)
        - PULL_REQUEST: Source-control pull request
        - MEETING: Meeting record (e.g. Zoom)
        - PRODUCT: Product entity (CRM)
        - DEAL: Deal/opportunity entity (CRM)
        - CASE: Case entity (CRM/support)
        - TASK: Task entity
        - ARTIFACT: Generated/derived artifact
        - CODE_FILE: Source-code file
        - SQL_TABLE: SQL table object
        - SQL_VIEW: SQL view object
        - OTHERS: Miscellaneous content types
      enum:
      - FILE
      - DRIVE
      - WEBPAGE
      - DATABASE
      - DATASOURCE
      - MESSAGE
      - MAIL
      - GROUP_MAIL
      - TICKET
      - COMMENT
      - INLINE_COMMENT
      - CONFLUENCE_PAGE
      - CONFLUENCE_BLOGPOST
      - SHAREPOINT_PAGE
      - SHAREPOINT_LIST
      - SHAREPOINT_LIST_ITEM
      - SHAREPOINT_DOCUMENT_LIBRARY
      - LINK
      - PROJECT
      - PULL_REQUEST
      - MEETING
      - PRODUCT
      - DEAL
      - CASE
      - TASK
      - ARTIFACT
      - CODE_FILE
      - SQL_TABLE
      - SQL_VIEW
      - OTHERS
      example: FILE
    ConnectorNameEnum:
      type: string
      description: |
        Name of the source connector. Mirrors the values of the backend
        `Connectors` enum (`backend/python/app/config/constants/arangodb.py`);
        records store the enum value (e.g. Google Drive is `DRIVE`,
        SharePoint Online is `SHAREPOINT ONLINE`), not the enum member name.
      enum:
      - DRIVE
      - DRIVE WORKSPACE
      - GMAIL
      - GMAIL WORKSPACE
      - CALENDAR
      - ONEDRIVE
      - SHAREPOINT ONLINE
      - OUTLOOK
      - OUTLOOK PERSONAL
      - OUTLOOK CALENDAR
      - MICROSOFT TEAMS
      - NOTION
      - NOTION PERSONAL
      - SLACK
      - SLACK WORKSPACE
      - KB
      - CONFLUENCE
      - CONFLUENCE DATA CENTER
      - CONFLUENCE DATA CENTER PERSONAL
      - JIRA
      - JIRA PERSONAL
      - JIRA CLOUD PERSONAL
      - JIRA DATA CENTER
      - JIRA DATA CENTER PERSONAL
      - BOX
      - NEXTCLOUD
      - DROPBOX
      - DROPBOX PERSONAL
      - WEB
      - BOOKSTACK
      - DRUPAL WIKI
      - GITHUB
      - GITHUB TEAMS
      - SERVICENOW
      - SALESFORCE
      - S3
      - MINIO
      - GCS
      - AZURE BLOB
      - AZURE FILES
      - LINEAR
      - ZAMMAD
      - ZENDESK
      - ZOOM
      - GITLAB
      - GITLAB PERSONAL
      - SNOWFLAKE
      - POSTGRESQL
      - MARIADB
      - UNKNOWN
      - RSS
      - LOCAL_FS
      - CODING_SANDBOX
      - DATABASE_SANDBOX
      - IMAGE_GENERATION
      - ATTACHMENTS
      - DEMO
      - SMB
      - CIFS
      example: DRIVE
    StageStateSummary:
      type: object
      additionalProperties: false
      description: |
        Status of one pipeline stage (e.g. `classify`) for the record's current
        content revision.
      required:
      - stage
      - status
      - reason
      - attempt
      - startedAtMs
      - finishedAtMs
      - updatedAtMs
      properties:
        stage:
          type: string
          description: Pipeline stage name.
          example: classify
        status:
          type: string
          description: Stage status (same values as `indexingStatus`).
          example: COMPLETED
        reason:
          type: string
          nullable: true
          description: Failure or skip reason, when there is one.
        attempt:
          type: integer
          description: Number of times this stage has run for this revision.
        startedAtMs:
          type: integer
          format: int64
          nullable: true
        finishedAtMs:
          type: integer
          format: int64
          nullable: true
        updatedAtMs:
          type: integer
          format: int64
          nullable: true
    GetRecordByIdResponseSchema:
      type: object
      additionalProperties: false
      description: |
        Response returned by GET /knowledgeBase/record/{recordId}.

        For a connected app with a limit, a collection or folder the limit
        leaves out is not named: `knowledgeBase` and `folder` are `null` for
        it, as are the record's own `recordGroupId` (with `externalGroupId`),
        `rootRecordGroupId` and `parentNodeId` (with `externalParentId`).
        `externalParentId` is also `null` when there is no `parentNodeId` to
        check it by, unless the limit covers the record's whole app.
        `fileRecord.path` is `null` unless the limit covers the whole app or
        collection; `webUrl` is kept.
      required:
      - record
      - knowledgeBase
      - folder
      - metadata
      - permissions
      properties:
        record:
          type: object
          additionalProperties: false
          required:
          - id
          - orgId
          - recordName
          - externalRecordId
          - connectorId
          - connectorName
          - recordType
          - origin
          - version
          - createdAtTimestamp
          - updatedAtTimestamp
          - sourceCreatedAtTimestamp
          - sourceLastModifiedTimestamp
          - indexingStatus
          - extractionStatus
          - isDeleted
          - isArchived
          - isVLMOcrProcessed
          - mimeType
          - sizeInBytes
          - webUrl
          - fileRecord
          - mailRecord
          - ticketRecord
          properties:
            id:
              type: string
            orgId:
              type: string
            recordName:
              type: string
            externalRecordId:
              type: string
            externalRootGroupId:
              type: string
              nullable: true
            externalGroupId:
              type: string
              nullable: true
            externalParentId:
              type: string
              nullable: true
            externalRevisionId:
              type: string
              nullable: true
            recordGroupId:
              type: string
              nullable: true
            rootRecordGroupId:
              type: string
              nullable: true
              description: |
                Internal identifier of the top-most record group in this record's
                chain. A group with no parent is its own root, so this is null
                only for records written before the field existed, or by
                connectors that do not set it.
            accessRule:
              type: string
              enum:
              - OPEN
              - STRICT
              - RESTRICTED
              description: |
                How this record's own permissions combine with its ancestors'.
                OPEN: an accessible parent, or a direct grant, is enough.
                STRICT: every ancestor up to the connector must be accessible too.
                RESTRICTED: strict, and a grant on the record itself is required.
                Absent on records written before the field existed; read as OPEN.
            uploadedBy:
              type: string
              nullable: true
              description: |
                User id of whoever uploaded the file to the knowledge base.
                Absent for connector records and for files uploaded before the
                field existed.
            sourceTimestampOrigin:
              type: string
              description: |
                Knowledge-base uploads only: what set sourceCreatedAtTimestamp
                and sourceLastModifiedTimestamp. `upload`: the upload time (the
                file came without a last-modified time); `file`: the file's
                last-modified time sent with the upload; `content`: dates the
                document states in its header (CONTENT_DOCUMENT_DATES), stored at
                midnight UTC of each stated day. Absent for connector records,
                whose timestamps are the source system's, and for files uploaded
                before the field existed.
            uploadSourceCreatedAtTimestamp:
              type: integer
              format: int64
              nullable: true
              description: |
                With sourceTimestampOrigin `content`: the
                sourceCreatedAtTimestamp the upload had set, kept so it can be
                restored.
            uploadSourceLastModifiedTimestamp:
              type: integer
              format: int64
              nullable: true
              description: |
                With sourceTimestampOrigin `content`: the
                sourceLastModifiedTimestamp the upload had set.
            uploadSourceTimestampOrigin:
              type: string
              description: |
                With sourceTimestampOrigin `content`: what had set the upload's
                values (`upload` or `file`).
            connectorId:
              type: string
            connectorName:
              $ref: '#/components/schemas/ConnectorNameEnum'
            recordType:
              $ref: '#/components/schemas/RecordTypeEnum'
            origin:
              type: string
            version:
              type: integer
            isLatestVersion:
              type: boolean
              nullable: true
            createdAtTimestamp:
              type: integer
              format: int64
            updatedAtTimestamp:
              type: integer
              format: int64
            sourceCreatedAtTimestamp:
              type: integer
              format: int64
            sourceLastModifiedTimestamp:
              type: integer
              format: int64
            lastSyncTimestamp:
              type: integer
              format: int64
              nullable: true
            lastIndexTimestamp:
              type: integer
              format: int64
            lastExtractionTimestamp:
              type: integer
              format: int64
            entityExtractionStatus:
              type: string
              pattern: ^[A-Z_]{1,32}$
              description: |
                Where named-entity extraction (people, organizations, dates and
                other values found in the content) stands for this record:
                NOT_STARTED, IN_PROGRESS, COMPLETED, PARTIAL, FAILED or SKIPPED.
                Absent when no status has been stored on the record; read that
                as not extracted. New values may be added, so treat an unknown
                one as not finished.
            lastEntityExtractionTimestamp:
              type: integer
              format: int64
              nullable: true
              description: When named-entity extraction last ran on the record (epoch milliseconds). Absent until it is written.
            entityExtractionStrategy:
              type: string
              nullable: true
              description: |
                How the named entities were found: `deterministic` (pattern
                recognizers only), `single_call` (one model call) or `agent`.
                Absent until it is written.
            entityExtractorVersion:
              type: string
              nullable: true
              description: Version of the named-entity extractor that produced the record's entities, for example `ner-1`. Absent until it is written.
            secretsRedacted:
              type: integer
              description: Credentials (keys, tokens, passwords) removed from a code repository file before it was indexed. Present once the file has been scanned, 0 when nothing was found.
            processingStartedAt:
              type: integer
              format: int64
              nullable: true
            queuedAtTimestamp:
              type: integer
              format: int64
              nullable: true
            retryNotBefore:
              type: integer
              format: int64
              nullable: true
              description: |
                Set while the record is QUEUED because its source rate-limited
                the content fetch: the earliest time (epoch milliseconds)
                indexing reads it again. `reason` then says when indexing
                resumes. Null or absent once the source serves the record or
                indexing ends; a value on a record that is no longer QUEUED is
                left over from an earlier wait and means nothing.
            parsingStatus:
              type: string
              nullable: true
            indexingStatus:
              type: string
            hasIndexedCopy:
              type: boolean
              description: |
                True after the record is indexed (every COMPLETED write, including the upgrade
                backfill for records indexed earlier), and false once it is marked EMPTY. A later
                re-queue or a failed re-index leaves it as it is, so search keeps returning the
                previous indexed copy until the new version is indexed. Absent until the first
                COMPLETED or EMPTY write sets it.
            extractionStatus:
              type: string
            reason:
              type: string
              nullable: true
            isDeleted:
              type: boolean
            isArchived:
              type: boolean
            deletedByUserId:
              type: string
              nullable: true
            restoredAtTimestamp:
              type: integer
              format: int64
              nullable: true
              description: |
                When a restore last brought this knowledge-base file back from
                the trash and queued it to be indexed again (epoch
                milliseconds). Absent on records never restored, on folders, and
                on files restored while their indexing was turned off.
            isDirty:
              type: boolean
              nullable: true
            isVLMOcrProcessed:
              type: boolean
              nullable: true
            mimeType:
              type: string
              nullable: true
            sizeInBytes:
              type: integer
              format: int64
              nullable: true
            md5Checksum:
              type: string
              nullable: true
            virtualRecordId:
              type: string
              nullable: true
            contentRev:
              type: string
              nullable: true
              description: |
                Revision of the record's content, 16 lowercase hex characters:
                the start of the SHA-256 of the content the indexer received
                for the record. If a record still has no revision stored when
                its vectors are written, a digest of its parsed blocks is
                stored instead.
                Identical content gives the same value, and a copy whose content
                matches another record carries that record's value.
                `stageStates` describes this revision. Set when indexing
                starts; absent on records not indexed since pipeline stages
                were introduced.
              example: 78f3f276290c9f81
            summaryDocumentId:
              type: string
              nullable: true
            storageDocumentId:
              type: string
              nullable: true
            webUrl:
              type: string
              nullable: true
            previewRenderable:
              type: boolean
              nullable: true
            isShared:
              type: boolean
              nullable: true
            isDependentNode:
              type: boolean
              nullable: true
            parentNodeId:
              type: string
              nullable: true
            hideWeburl:
              type: boolean
              nullable: true
            isInternal:
              type: boolean
              nullable: true
            isPlaceholder:
              type: boolean
              nullable: true
              description: True for placeholder/stub records standing in for an out-of-scope ancestor (rendered read-only, no content actions; excluded from search and indexing).
            fileRecord:
              type: object
              nullable: true
              additionalProperties: false
              required:
              - id
              - orgId
              - name
              - extension
              - isFile
              properties:
                id:
                  type: string
                orgId:
                  type: string
                name:
                  type: string
                extension:
                  type: string
                etag:
                  type: string
                  nullable: true
                ctag:
                  type: string
                  nullable: true
                md5Checksum:
                  type: string
                  nullable: true
                quickXorHash:
                  type: string
                  nullable: true
                crc32Hash:
                  type: string
                  nullable: true
                sha1Hash:
                  type: string
                  nullable: true
                sha256Hash:
                  type: string
                  nullable: true
                mimeType:
                  type: string
                  nullable: true
                sizeInBytes:
                  type: integer
                  format: int64
                  nullable: true
                isFile:
                  type: boolean
                webUrl:
                  type: string
                  nullable: true
                  description: |
                    Where the file opens in its source. Kept for a connected
                    app with a limit too; it can contain the names of the
                    folders above the file.
                path:
                  type: string
                  nullable: true
                  description: |
                    The file's path in its source, which names every folder
                    above it. `null` for a connected app whose limit does not
                    cover the file's whole app or collection.
                localFsRelativePath:
                  type: string
                  nullable: true
                  description: The same path on local storage; `null` in the same cases as `path`.
            mailRecord:
              type: object
              nullable: true
              additionalProperties: false
              properties: {}
            ticketRecord:
              type: object
              nullable: true
              additionalProperties: false
              properties: {}
        stageStates:
          type: array
          description: |
            Per-stage pipeline status for the record's current content revision.
            Empty for records indexed before pipeline stages existed. The
            `classify` stage's status is mirrored on `record.extractionStatus`.
          items:
            $ref: '#/components/schemas/StageStateSummary'
        knowledgeBase:
          type: object
          nullable: true
          additionalProperties: false
          required:
          - id
          - name
          - orgId
          properties:
            id:
              type: string
            name:
              type: string
            orgId:
              type: string
        folder:
          type: object
          nullable: true
          additionalProperties: false
          required:
          - id
          - name
          properties:
            id:
              type: string
            name:
              type: string
        metadata:
          type: object
          additionalProperties: false
          required:
          - languages
          - topics
          - subcategories1
          - subcategories2
          - subcategories3
          - departments
          - categories
          properties:
            languages:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - id
                - name
                properties:
                  id:
                    type: string
                  name:
                    type: string
            topics:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - id
                - name
                properties:
                  id:
                    type: string
                  name:
                    type: string
            subcategories1:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - id
                - name
                properties:
                  id:
                    type: string
                  name:
                    type: string
            subcategories2:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - id
                - name
                properties:
                  id:
                    type: string
                  name:
                    type: string
            subcategories3:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - id
                - name
                properties:
                  id:
                    type: string
                  name:
                    type: string
            departments:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - id
                - name
                properties:
                  id:
                    type: string
                  name:
                    type: string
            categories:
              type: array
              items:
                type: object
                additionalProperties: false
                required:
                - id
                - name
                properties:
                  id:
                    type: string
                  name:
                    type: string
        permissions:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - id
            - name
            - type
            - relationship
            - accessType
            properties:
              id:
                type: string
              name:
                type: string
              type:
                type: string
              relationship:
                type: string
                enum:
                - OWNER
                - WRITER
                - READER
              accessType:
                type: string
    GetRecordContentResponseSchema:
      type: object
      additionalProperties: false
      description: |
        Response returned by GET /connectors/record/{recordId}/content.

        `content` is the record's full parsed content flattened into a single
        plain-text string: a metadata header (title, source, key fields, and a
        short summary), then the record's block/table text in reading order, and
        finally a foreign-key related-tables footer for `SQL_TABLE` records.

        For `TICKET` records (e.g. Jira) the metadata header is refreshed with
        live ticket fields (status, assignee, comments) at request time rather
        than the last-indexed snapshot. `content` may be empty for an indexed
        record with no extractable text (e.g. image-only).

        A record that exists and that the caller may read, but whose content
        is not indexed yet (`indexingStatus` other than `COMPLETED`), has no
        parsed text. `content` is then a description of the record instead:
        its metadata header (name, link, dates, type-specific fields) followed
        by a paragraph that starts `Not indexed:` and names the status, e.g.
        `(status: AUTO_INDEX_OFF)`. It is not the record's text.

        `content` is the literal `No record found` when the caller may read
        an indexed record but its stored content could not be loaded. An id
        that does not exist, a record in the trash, and a record the caller
        may not read all answer `403` instead.

        An unbudgeted read returns at most 140,000 characters of `content`. A
        longer record is cut there, the content ends with a marker line, and
        the response carries `truncated: true` and `totalChars`.
      required:
      - content
      properties:
        content:
          type: string
          description: The record's full parsed content as a single plain-text string; for a record whose content is not indexed yet, a description of the record and its indexing status instead (see above). In a budgeted read, the part of the record (or thread) that fit. An unbudgeted read returns at most 140,000 characters; a longer record is cut there and the content ends with a truncation marker (see `truncated`).
        truncated:
          type: boolean
          description: Present and true only on an unbudgeted read whose content was cut to fit 140,000 characters, marker included. `totalChars` is then the length of the whole content.
        totalChars:
          type: integer
          description: Present only with `truncated`. The length of the record's whole content, in characters.
        mode:
          type: string
          enum:
          - record
          - thread
          description: Budgeted reads only. Which kind of read this was.
        recordId:
          type: string
          description: Budgeted record reads only. The record read.
        order:
          type: string
          enum:
          - in_order
          - relevance
          - extract
          description: 'Budgeted record reads only. `relevance` when `query` chose which blocks to show; the blocks are then not contiguous. `extract` when `extract=true` was asked and the reader model answered: `content` is the passages it copied out (told to copy word for word; see `extract.unverifiedLines`), not a page of the record. An extract is one response, so `complete` is true and `nextStartBlock` null; whether the reader saw the whole record is `extract.sourceComplete`.'
        extract:
          type: object
          description: 'Reads with `extract=true` only. With `order: extract`, the reader model''s call. On a plain read returned because the reader could not answer, `error` alone.'
          properties:
            model:
              type: string
              nullable: true
              description: The model that read the record.
            provider:
              type: string
              nullable: true
            nothingRelevant:
              type: boolean
              description: True when the reader found nothing that answers `query`; `content` is then `NOTHING RELEVANT`.
            truncated:
              type: boolean
              description: True when the reader's reply was cut to fit `maxChars` (or 12,000 characters, whichever is smaller).
            unverifiedLines:
              type: integer
              description: 'Lines of `content` with words not found in the text the reader was given, as written: a paraphrase, or a misreading. Check them with a plain read. Every fragment with a letter or digit is checked, and a match may not run into a longer word or number (`$1,250` is not found in `$1,250,000`, nor `$1,250.` in `$1,250.99`). A note the reader adds in square brackets beside a quote (where a passage sits) is not checked; a markdown link''s label, and a line that is only a bracketed note, are. 0 means every quoted fragment was found, not that `content` is complete or that it quotes the right passage.'
            sourceChars:
              type: integer
              description: Characters of the record the reader was given.
            sourceComplete:
              type: boolean
              description: 'True when the reader was given the whole record. False when the record was longer than the reader''s 120,000 characters, or had more than 5,000 blocks, and it was given part of it: the blocks most relevant to `query`, or the start of the record when the relevance search found nothing or failed.'
            inputTokens:
              type: integer
            outputTokens:
              type: integer
            error:
              type: string
              description: Why there is no extract (the failure's type, or `EmptyReply`); `content` is then the plain read at `maxChars`.
        startBlock:
          type: integer
          description: Budgeted reads only. Where this read started (in a thread read, within the record at `startRecord`).
        totalBlocks:
          type: integer
          description: Budgeted record reads only. Blocks in the record.
        shownBlocks:
          type: array
          description: Budgeted record reads only. The block ranges shown, as `[first, last]` pairs.
          items:
            type: array
            items:
              type: integer
        complete:
          type: boolean
          description: Budgeted reads only. True when nothing of the record (or thread) is left to read after this one. A block larger than the largest `maxChars` (140000) is returned cut and given up; when nothing follows it, `complete` is true and `truncatedBy` is `clipped`.
        truncatedBy:
          type: string
          nullable: true
          description: 'Budgeted reads. Why the read stopped short: `chars`, `selection`, or `clipped` (a block larger than `maxChars` was cut; it takes precedence over the others). Null when the read lost nothing. `clipped` can come with `complete: true`: a block given up at the largest `maxChars` with nothing after it.'
        givenUpBlock:
          type: integer
          nullable: true
          description: 'Budgeted record reads only. A block larger than the largest `maxChars` (140000) that this read cut and gave up: no read can return the rest of it. Set in the read that gave it up, even when more of the record follows.'
        givenUpBlocks:
          type: array
          description: Thread reads only. Every block this read gave up at the largest `maxChars`, by record.
          items:
            type: object
            properties:
              recordId:
                type: string
              block:
                type: integer
        nextStartBlock:
          type: integer
          nullable: true
          description: 'Pass as `startBlock` to read on; null when nothing is left. In a thread read it is the block of the record at `nextStartRecord` (0 unless that record was cut short). A block larger than `maxChars` holds it on that block: send it again with a larger `maxChars` (up to 140000) to read the block whole.'
        threadRecordCount:
          type: integer
          description: Thread reads only. Records in the thread the caller may see.
        startRecord:
          type: integer
          description: Thread reads only. Where this read started.
        nextStartRecord:
          type: integer
          nullable: true
          description: 'Thread reads only. Pass as `startRecord`, with `nextStartBlock` as `startBlock`, to read on. It stays on a record that was cut short until that record has been read to its end. A block larger than `maxChars` holds the cursor on that block; send the same cursor with a larger `maxChars` to read it. Null when nothing is left to read, and `complete` is then true. A block given up at the largest `maxChars` is named in the text, and its record''s entry in `records` has `truncatedBy: clipped`.'
        records:
          type: array
          description: Thread reads only. The records shown, oldest first.
          items:
            type: object
            properties:
              recordId:
                type: string
              recordName:
                type: string
                nullable: true
              startBlock:
                type: integer
              complete:
                type: boolean
              truncatedBy:
                type: string
                nullable: true
              givenUpBlock:
                type: integer
                nullable: true
              nextStartBlock:
                type: integer
                nullable: true
        unreadableRecordIds:
          type: array
          description: Thread reads only. Records of the thread the caller may see whose content could not be loaded.
          items:
            type: string
        threads:
          type: array
          description: Thread reads of a Slack record in no single thread only (several channel messages in one record, or a message without replies). The threads its messages started whose replies follow it in `records`, in the order their first messages were posted; empty when none of its messages has replies the caller may see.
          items:
            type: object
            additionalProperties: false
            properties:
              threadRecordGroupId:
                type: string
                description: The thread's record group.
              recordCount:
                type: integer
                description: Replies of this thread the caller may see.
        threadsNotRead:
          type: integer
          description: Thread reads of a Slack record in no single thread only. Threads of its messages left out because one read covers at most 10.
        chars:
          type: integer
          description: Budgeted reads only. Characters in `content`.
        maxChars:
          type: integer
          description: Budgeted reads only. The budget this read used.
    KnowledgeGraphNodeRefSchema:
      type: object
      additionalProperties: false
      description: Minimal identity reference for a node in the knowledge graph.
      required:
      - id
      - name
      - node_type
      - sub_type
      - is_record
      properties:
        id:
          type: string
          description: Node identifier. Pass it back as `nodeId` to open this node. When `is_record` is true it is also the Record ID accepted by GET /connectors/record/{recordId}/content.
        name:
          type: string
        node_type:
          type: string
          description: One of `app`, `recordGroup`, `folder`, `record`.
        sub_type:
          type: string
          nullable: true
          description: e.g. `TICKET`, `CONFLUENCE_PAGE`, `PROJECT`, `COLLECTION`.
        is_record:
          type: boolean
          description: True for record and folder nodes — the nodes whose content can be read via GET /connectors/record/{recordId}/content.
    KnowledgeGraphNodeRowSchema:
      type: object
      additionalProperties: false
      description: |
        One row in a navigate listing. Carries the identity fields of
        KnowledgeGraphNodeRefSchema (inlined rather than composed, so this
        object can stay closed) plus display detail.
      required:
      - id
      - name
      - node_type
      - sub_type
      - is_record
      - has_children
      - detail
      properties:
        id:
          type: string
        name:
          type: string
        node_type:
          type: string
          description: 'One of `recordGroup`, `folder`, `record`, or `app`. A listing holds `app` nodes only at the root of a connected app whose limit names spaces, folders or files as well as whole sources: there it lists those sources.'
        sub_type:
          type: string
          nullable: true
        is_record:
          type: boolean
        has_children:
          type: boolean
          description: Whether this node can itself be opened with `nodeId`.
        detail:
          type: string
          nullable: true
          description: e.g. size, indexing status, or relationship type.
        web_url:
          type: string
          nullable: true
          description: Link to the record in its source system. Records that carry a relative URL (uploaded/KB records) are resolved against the configured frontend public URL (see POST /configurationManager/frontendPublicUrl). The value is null when that host is not configured.
        indexing_status:
          type: string
          nullable: true
        source_created_at:
          type: integer
          format: int64
          nullable: true
          description: Creation time in the source system, epoch milliseconds. Null when the underlying node did not carry one.
        source_modified_at:
          type: integer
          format: int64
          nullable: true
        level:
          type: integer
          description: 1-based nesting depth from the navigated parent. Always 1 for a `depth=1` listing; 2 or 3 for deeper rows when `depth` > 1.
        context_summary:
          type: string
          nullable: true
    KnowledgeGraphPaginationSchema:
      type: object
      additionalProperties: false
      description: Pagination envelope for a navigate listing.
      required:
      - page
      - limit
      - total
      - has_next
      - has_prev
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
          description: Total children of the current node, ignoring pagination.
        has_next:
          type: boolean
        has_prev:
          type: boolean
    NavigateKnowledgeGraphResponseSchema:
      type: object
      additionalProperties: false
      description: |
        Response returned by GET /connectors/navigate.

        Field names are snake_case, matching the knowledge graph's internal
        view models. `text` carries the same flat-text rendering PipesHub's
        own agent sees for this node; the remaining fields carry the same
        information in structured form.
      required:
      - current
      - breadcrumbs
      - rows
      - related
      - pagination
      - web_url
      - indexing_status
      - connector
      - text
      properties:
        current:
          allOf:
          - $ref: '#/components/schemas/KnowledgeGraphNodeRefSchema'
          nullable: true
          description: The node that was opened. Null at the root listing.
        breadcrumbs:
          type: array
          description: Root to parent, not including `current`.
          items:
            $ref: '#/components/schemas/KnowledgeGraphNodeRefSchema'
        rows:
          type: array
          description: The current node's children for this page. With `depth` > 1 this is a flat list of all descendants up to that depth, each row carrying its own `level`.
          items:
            $ref: '#/components/schemas/KnowledgeGraphNodeRowSchema'
        related:
          type: array
          description: Cross-referenced records (non-containment edges), e.g. the Confluence page linked from a Jira ticket. Page 1 only.
          items:
            $ref: '#/components/schemas/KnowledgeGraphNodeRowSchema'
        pagination:
          allOf:
          - $ref: '#/components/schemas/KnowledgeGraphPaginationSchema'
          nullable: true
        web_url:
          type: string
          nullable: true
        indexing_status:
          type: string
          nullable: true
        connector:
          type: string
          nullable: true
        context_block:
          type: string
          nullable: true
          description: Type-specific metadata for the current node when it is a record — for a ticket, status, assignee, priority and dates.
        text:
          type: string
          description: |
            Flat-text rendering of this view: breadcrumbs, the current node's
            metadata, the children listing with an id per row, `Related:`, and
            a closing `Next:` line naming a follow-up call.

            Shape depends on the page: pages after the first omit the header,
            breadcrumbs and related rows to stay compact, while the structured
            fields above remain complete. Capped at 25,000 bytes, with a
            truncation marker appended when exceeded.
    KnowledgeGraphLookupMatchSchema:
      type: object
      additionalProperties: false
      description: A single record resolved from an identifier.
      required:
      - id
      - name
      - record_type
      - connector_name
      - web_url
      - indexing_status
      - identifier_used
      properties:
        id:
          type: string
          description: The Record ID. Pass it to GET /connectors/record/{recordId}/content to read the record, or as `nodeId` to GET /connectors/navigate to list what is under it.
        name:
          type: string
        record_type:
          type: string
          nullable: true
        connector_name:
          type: string
          nullable: true
        web_url:
          type: string
          nullable: true
        indexing_status:
          type: string
          nullable: true
        identifier_used:
          type: string
          description: Which of the supplied identifiers produced this match.
        external_id:
          type: string
          nullable: true
          description: e.g. `PA-1787`, a Confluence page id, a Drive file id.
        context_block:
          type: string
          nullable: true
          description: Type-specific metadata for the record — for a ticket, status, assignee, priority and dates.
    LookupRecordResponseSchema:
      type: object
      additionalProperties: false
      description: |
        Response returned by GET /connectors/record/lookup.

        Field names are snake_case, matching the knowledge graph's internal
        view models. A miss is a 200 with an empty `matches` and the input
        echoed in `not_found_identifiers` — see the endpoint description.
      required:
      - matches
      - ambiguous
      - not_found_identifiers
      - text
      properties:
        matches:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeGraphLookupMatchSchema'
        ambiguous:
          type: boolean
          description: True when one identifier resolved to more than one accessible record. Present the choice rather than taking the first, or retry with `connectorName`.
        not_found_identifiers:
          type: array
          description: Identifiers that resolved to nothing the caller can access.
          items:
            type: string
        searched_connectors:
          type: object
          description: Per-identifier list of the connector types that were searched, so a miss can be retried against a different `connectorName`. Keys are the identifiers exactly as supplied.
          additionalProperties:
            type: array
            items:
              type: string
        text:
          type: string
          description: Flat-text rendering of the matches — each match's metadata block followed by a `Next:` line naming a follow-up call — and a line per miss naming the connectors that were searched. Capped at 25,000 bytes.
    DeleteRecordResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned by DELETE /knowledgeBase/record/{recordId}.
      required:
      - success
      - message
      - recordId
      properties:
        success:
          type: boolean
          enum:
          - true
        message:
          type: string
        recordId:
          type: string
        connector:
          type: string
          nullable: true
        timestamp:
          type: integer
          format: int64
          nullable: true
        softDeleted:
          type: boolean
          description: True when the record went to the trash instead of being removed
        batchId:
          type: string
          nullable: true
          description: The delete batch; restoring any record in it restores all of it
        vectorCleanupPending:
          type: boolean
          description: The record is deleted, but removing its embeddings is still owed
        vectorCleanupFailedRecordIds:
          type: array
          items:
            type: string
        vectorCleanupFailedVirtualRecordIds:
          type: array
          items:
            type: string
    RestoredRecordSchema:
      type: object
      additionalProperties: false
      required:
      - recordId
      properties:
        recordId:
          type: string
        name:
          type: string
          nullable: true
          description: The name it has now
        renamedFrom:
          type: string
          description: Its name before restore, when another item next to it had taken that name
    RestoreRecordResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned by POST /knowledgeBase/record/{recordId}/restore.
      required:
      - success
      - message
      - restoredRecords
      properties:
        success:
          type: boolean
          enum:
          - true
        message:
          type: string
        batchId:
          type: string
          nullable: true
          description: The delete batch that was restored
        restoredRecords:
          type: array
          items:
            $ref: '#/components/schemas/RestoredRecordSchema'
        reindexPending:
          type: boolean
          description: Some restored files could not be queued for indexing
        reindexPendingRecordIds:
          type: array
          items:
            type: string
          description: Files to reindex by hand to make them searchable again
        reindexPendingReason:
          type: string
        renamePendingRecordIds:
          type: array
          items:
            type: string
          description: Items restored under a name another item next to them has; rename them
        renamePendingReason:
          type: string
    TrashItemSchema:
      type: object
      additionalProperties: false
      description: What one delete removed (a folder with its contents, or every item of a multi-select); restoring it brings back all of it.
      required:
      - id
      - isFolder
      - parentInTrash
      - itemCount
      - deletedAtTimestamp
      properties:
        id:
          type: string
          description: Record ID to restore
        name:
          type: string
          nullable: true
        recordType:
          type: string
          nullable: true
        isFolder:
          type: boolean
          description: A folder, deleted with everything in it
        mimeType:
          type: string
          nullable: true
        sizeInBytes:
          type: integer
          format: int64
          nullable: true
        parentId:
          type: string
          nullable: true
          description: The folder it was in; null at the collection's top level
        parentName:
          type: string
          nullable: true
        parentInTrash:
          type: boolean
          description: That folder is in the trash too; restore it first
        itemCount:
          type: integer
          minimum: 0
          description: Records this delete removed, all of which a restore brings back
        rootCount:
          type: integer
          minimum: 1
          description: Items selected in the delete; more than one for a multi-select delete, which is one item here
        otherRootNames:
          type: array
          items:
            type: string
          description: Names of up to three of the other items selected with this one
        deletedAtTimestamp:
          type: integer
          format: int64
        deletedBy:
          type: object
          nullable: true
          additionalProperties: false
          properties:
            name:
              type: string
              nullable: true
            email:
              type: string
              nullable: true
        removableAfterTimestamp:
          type: integer
          format: int64
          nullable: true
          description: From when the scheduled cleanup may remove it for good; null when unknown
    ListTrashResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned by GET /knowledgeBase/{kbId}/trash.
      required:
      - success
      - items
      - pagination
      properties:
        success:
          type: boolean
          enum:
          - true
        items:
          type: array
          items:
            $ref: '#/components/schemas/TrashItemSchema'
        pagination:
          type: object
          additionalProperties: false
          required:
          - page
          - limit
          - totalCount
          - totalPages
          properties:
            page:
              type: integer
            limit:
              type: integer
            totalCount:
              type: integer
            totalPages:
              type: integer
        retention:
          type: object
          nullable: true
          additionalProperties: false
          required:
          - minAgeMs
          properties:
            minAgeMs:
              type: integer
              format: int64
              description: Items stay at least this long before the cleanup may remove them
    RestoreRecordsRequestBody:
      type: object
      description: Request body for POST /knowledgeBase/records/restore. Fields other than `recordIds` are dropped by the validator, not refused.
      required:
      - recordIds
      properties:
        recordIds:
          type: array
          minItems: 1
          maxItems: 100
          description: Record ids to restore. An id listed more than once is restored, and answered, once.
          items:
            type: string
            minLength: 1
            pattern: \S
            description: Whitespace around an id is removed first, so an id made only of whitespace is refused as empty.
    RestoreRecordsResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned by POST /knowledgeBase/records/restore.
      required:
      - success
      - restoredCount
      - failedCount
      - results
      properties:
        success:
          type: boolean
          description: True when every requested record was restored
        restoredCount:
          type: integer
          description: Records restored, counting those restored along with them
        failedCount:
          type: integer
        results:
          type: array
          description: |
            One entry per requested id: `recordId`, `success`, `code`, and either the
            restore response fields or a `reason` that says what to do next.
          items:
            $ref: '#/components/schemas/RestoreRecordsResultItemSchema'
    RestoreRecordsResultItemSchema:
      type: object
      additionalProperties: false
      description: |
        The outcome for one id of POST /knowledgeBase/records/restore. A restored item
        carries the fields of RestoreRecordResponseSchema; a refused one carries `reason`,
        and, when the refusal names other records, `blockedRecordId` plus the snake_case
        fields below (`external_id`, `conflicting_record_id`, `conflicting_record_name`).
      required:
      - recordId
      - success
      properties:
        recordId:
          type: string
        success:
          type: boolean
        code:
          type: integer
          description: The status the single restore would have answered (200, 403, 404, 409)
        reason:
          type: string
          description: Why it was not restored, and what to do next
        message:
          type: string
          description: Present on success
        batchId:
          type: string
          nullable: true
          description: The delete batch that was restored; `null` when the record was not in the trash
        restoredRecords:
          type: array
          description: Present on success; empty when the record was not in the trash
          items:
            $ref: '#/components/schemas/RestoredRecordSchema'
        reindexPending:
          type: boolean
          description: Some restored files could not be queued for indexing
        reindexPendingRecordIds:
          type: array
          items:
            type: string
          description: Files to reindex by hand to make them searchable again
        reindexPendingReason:
          type: string
        renamePendingRecordIds:
          type: array
          items:
            type: string
          description: Items restored under a name another item next to them has; rename them
        renamePendingReason:
          type: string
        blockedRecordId:
          type: string
          description: The item a refusal is about
        external_id:
          type: string
          description: The source item two of the restored items came from
        conflicting_record_id:
          type: string
          description: The live item that holds this item's place
        conflicting_record_name:
          type: string
          nullable: true
        missing:
          type: array
          items:
            type: string
          description: Items of the batch that were no longer in the trash
        parentId:
          type: string
          nullable: true
          description: The folder still in the trash that must be restored first
    reIndexRecordResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned by POST /knowledgeBase/reindex/record/{recordId}.
      required:
      - success
      - message
      - eventPublished
      - depth
      properties:
        success:
          type: boolean
          enum:
          - true
        message:
          type: string
        recordId:
          type: string
          nullable: true
        recordName:
          type: string
          nullable: true
        connector:
          type: string
          nullable: true
        eventPublished:
          type: boolean
        userRole:
          type: string
          nullable: true
        depth:
          type: integer
    ReIndexRecordGroupResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned by POST /knowledgeBase/reindex/record-group/{recordGroupId}.
      required:
      - success
      - message
      - recordGroupId
      - depth
      - connectorId
      - connector
      - eventPublished
      properties:
        success:
          type: boolean
          enum:
          - true
        message:
          type: string
        recordGroupId:
          type: string
        depth:
          type: integer
        connectorId:
          type: string
          description: Id of the connector instance the record group belongs to
        connector:
          type: string
          nullable: true
        eventPublished:
          type: boolean
    UploadLimitsResponseSchema:
      type: object
      additionalProperties: false
      description: Upload constraints returned by GET /knowledgeBase/limits.
      required:
      - maxFilesPerRequest
      - maxFileSizeBytes
      properties:
        maxFilesPerRequest:
          type: integer
          minimum: 1
          example: 1000
          description: Maximum number of files per upload request
        maxFileSizeBytes:
          type: integer
          minimum: 1
          example: 31457280
          description: Maximum file size in bytes (default 30MB when platform settings unavailable)
    UploadStreamSSEEvent:
      type: object
      description: |
        Server-Sent Event envelope for the KB streaming upload endpoint
        (`POST /knowledgeBase/{kbId}/upload`, with optional `folderId` query param).

        These endpoints respond with `Content-Type: text/event-stream`: the upload
        and its per-file progress are a single request. The body streams one
        terminal event per file, then a final `done` summary, then closes. `data`
        is a JSON-encoded string whose decoded shape depends on `event`:

        - `file:succeeded` — see `UploadSucceededFileDetail`. The file was
          uploaded and its record created; content indexing then continues
          asynchronously.
        - `file:failed` — see `UploadFailedFileDetail`. Covers files rejected up
          front (oversize / unsupported type — these carry `reason`), files that
          failed the storage upload (`stage: "upload"`), and files the indexing
          service could not create (`stage: "index"`).
        - `done` — see `UploadDoneSummary`. Final event; the stream closes after it.
        - `error` — `{ "message": string }`. Emitted only on a catastrophic
          mid-stream failure (after the 200 headers were already sent), then the
          stream closes. Clients MUST treat any file without a terminal
          `file:succeeded` / `file:failed` as failed when this is received.

        The stream also emits SSE comment heartbeats (`: keepalive`) roughly every
        1s during slow work; these carry no `event`/`data` and should be ignored.
        Authentication, permission, and request-shape failures occur BEFORE the
        stream starts and are returned as ordinary 4xx JSON errors (not stream
        events).
      properties:
        event:
          type: string
          enum:
          - file:succeeded
          - file:failed
          - done
          - error
        data:
          type: string
          description: JSON-encoded event payload. Shape depends on `event`.
    IndexingStatusFilter:
      type: string
      description: |
        Indexing status used to filter which records are included in a scoped
        reindex (record or record-group). Omit `statusFilters` to reindex all
        descendants regardless of status. The statuses records carry are
        `NOT_STARTED`, `QUEUED`, `IN_PROGRESS`, `COMPLETED`, `FAILED`,
        `FILE_TYPE_NOT_SUPPORTED`, `AUTO_INDEX_OFF`, `EMPTY` and `PASSWORD_PROTECTED`.
        Any other string is accepted too (no validator checks the value) and simply
        matches no record.
    ReindexRecordRequestBody:
      type: object
      description: |
        Optional body for single-record reindex. Only `depth` and `statusFilters` are read;
        any other field is dropped by the validator before the handler runs (there is no
        `force` option: the handler always sends `force: false`). No body, an empty object
        or an empty `statusFilters` list mean depth `0` and no status filter.
      properties:
        depth:
          type: integer
          minimum: -1
          maximum: 100
          default: 0
          description: |
            Child traversal depth (`0` = record only; higher values include
            descendants; `-1` = all of them; `100` is used by clients for folder-like reindex).
        statusFilters:
          type: array
          items:
            $ref: '#/components/schemas/IndexingStatusFilter'
          description: |
            When set, only records whose indexing status matches one of these
            values are reindexed (applies to the record and its descendants per `depth`).
    ReindexRecordGroupRequestBody:
      type: object
      description: |
        Optional body for record-group reindex. Only `depth` and `statusFilters` are read;
        any other field is dropped by the validator before the handler runs (there is no
        `force` option: the handler always sends `force: false`).
      properties:
        depth:
          type: integer
          minimum: -1
          maximum: 100
          default: 0
          description: |
            Depth of records under the record group to include. `-1` (everything) is applied,
            and answered, as `100`.
        statusFilters:
          type: array
          items:
            $ref: '#/components/schemas/IndexingStatusFilter'
          description: |
            When set, only records matching these indexing statuses are reindexed.
    ResyncConnectorRequestBody:
      type: object
      required:
      - connectorName
      properties:
        connectorName:
          type: string
          minLength: 1
          description: |
            The connector's type as the registry lists it, for example `RSS` or
            `Jira`. It names the sync event; the connector synced is always the
            one in the path.
          example: RSS
        fullSync:
          type: boolean
          description: When true, triggers a full sync instead of incremental.
          default: false
    ConnectorStats:
      type: object
      description: Statistics for a connector's records
      required:
      - success
      - data
      properties:
        success:
          type: boolean
        data:
          type: object
          required:
          - orgId
          - connectorId
          - origin
          - stats
          - byRecordType
          properties:
            orgId:
              type: string
            connectorId:
              type: string
            origin:
              type: string
              description: Where the records come from; `CONNECTOR` for a connector.
              example: CONNECTOR
              enum:
              - CONNECTOR
              - COLLECTION
            stats:
              type: object
              required:
              - total
              - indexingStatus
              properties:
                total:
                  type: integer
                  description: Records synced from the connector
                indexingStatus:
                  $ref: '#/components/schemas/ConnectorIndexingStatusCounts'
                extractionStatus:
                  type: object
                  description: Record counts by classification (`classify` stage) status.
                  additionalProperties:
                    type: integer
                entitiesStatus:
                  type: object
                  description: |
                    Record counts by named-entity extraction (`entities` stage)
                    status, read from each record's `entities` stage state on its
                    current revision. A record with no such state is not counted.
                  additionalProperties:
                    type: integer
            byRecordType:
              type: array
              description: The same counts per record type; empty before the first sync.
              items:
                type: object
                required:
                - recordType
                - total
                - indexingStatus
                properties:
                  recordType:
                    type: string
                    example: FILE
                  total:
                    type: integer
                  indexingStatus:
                    $ref: '#/components/schemas/ConnectorIndexingStatusCounts'
                  extractionStatus:
                    type: object
                    description: Record counts by classification (`classify` stage) status.
                    additionalProperties:
                      type: integer
                  entitiesStatus:
                    type: object
                    description: Record counts by named-entity extraction (`entities` stage) status.
                    additionalProperties:
                      type: integer
    ConnectorIndexingStatusCounts:
      type: object
      description: Number of records in each indexing status.
      additionalProperties:
        type: integer
      properties:
        NOT_STARTED:
          type: integer
        PAUSED:
          type: integer
        IN_PROGRESS:
          type: integer
        COMPLETED:
          type: integer
        FAILED:
          type: integer
        FILE_TYPE_NOT_SUPPORTED:
          type: integer
        AUTO_INDEX_OFF:
          type: integer
        EMPTY:
          type: integer
        ENABLE_MULTIMODAL_MODELS:
          type: integer
        QUEUED:
          type: integer
        SKIPPED:
          type: integer
        PASSWORD_PROTECTED:
          type: integer
    DateRangeFilter:
      type: object
      description: Date range filter with optional inclusive bounds (epoch ms).
      properties:
        gte:
          type: integer
          nullable: true
          description: Greater-than-or-equal bound (epoch ms).
        lte:
          type: integer
          nullable: true
          description: Less-than-or-equal bound (epoch ms).
    SizeRangeFilter:
      type: object
      description: Size range filter with optional inclusive bounds (bytes).
      properties:
        gte:
          type: integer
          nullable: true
          description: Greater-than-or-equal bound (bytes).
        lte:
          type: integer
          nullable: true
          description: Less-than-or-equal bound (bytes).
    FilterOption:
      type: object
      description: A single filter option for knowledge hub filters.
      required:
      - id
      - label
      properties:
        id:
          type: string
          description: Filter ID value to send in requests.
        label:
          type: string
          description: Display label for the filter.
        type:
          type: string
          nullable: true
          description: Additional type information (currently unused, may be null).
        connectorType:
          type: string
          nullable: true
          description: Connector type/name. Set only for entries in the `connectors` list.
    KnowledgeHubNode:
      type: object
      description: |
        One element of `items`. The live API keeps keys stable and sets
        inapplicable values to JSON `null` (not omitted).
      required:
      - id
      - name
      - nodeType
      - parentId
      - origin
      - connector
      - connectorId
      - recordType
      - recordGroupType
      - indexingStatus
      - reason
      - createdAt
      - updatedAt
      - sizeInBytes
      - mimeType
      - extension
      - webUrl
      - hasChildren
      - previewRenderable
      - permission
      - sharingStatus
      - isInternal
      - isPlaceholder
      properties:
        id:
          type: string
          description: Unique identifier for the node.
        name:
          type: string
          description: Display name of the node.
        nodeType:
          type: string
          enum:
          - app
          - recordGroup
          - folder
          - record
          description: Type of the node (app, recordGroup, folder, or record).
        parentId:
          type: string
          nullable: true
          description: |
            Parent node ID, or `null` at the root browse level. Also `null`
            for a connected app whose limit leaves the parent out: the node is
            listed, and the folder above it is not named.
        parent:
          type: object
          nullable: true
          description: |
            The parent this node is listed under, with what a client needs to
            open it and name it; `null` exactly when `parentId` is. It is the
            node's placement parent: an ancestor the user cannot open is
            replaced, never named.
          required:
          - id
          - nodeType
          properties:
            id:
              type: string
              description: Parent node ID.
            nodeType:
              type: string
              enum:
              - app
              - recordGroup
              - folder
              - record
              description: Parent node type; opened as `/nodes/{nodeType}/{id}`.
            name:
              type: string
              nullable: true
              description: Parent display name.
        origin:
          type: string
          enum:
          - COLLECTION
          - CONNECTOR
          description: Origin type.
        connector:
          type: string
          nullable: true
          description: Connector display name / key when applicable; otherwise `null`.
        connectorId:
          type: string
          nullable: true
          description: Connector instance id for records and groups that come from a connector; otherwise `null` (Collections, and app nodes).
        recordType:
          type: string
          nullable: true
          description: Record type when `nodeType` is `record`; otherwise `null`.
        recordGroupType:
          type: string
          nullable: true
          description: Record group type when `nodeType` is `recordGroup`; otherwise `null`.
        indexingStatus:
          type: string
          nullable: true
          description: Indexing status when `nodeType` is `record`; otherwise `null`.
        reason:
          type: string
          nullable: true
          description: Failure or status reason when set; otherwise `null`.
        isInternal:
          type: boolean
          description: True for internal/system nodes that do not originate from a source.
        isPlaceholder:
          type: boolean
          description: True for placeholder/stub nodes standing in for an out-of-scope ancestor (rendered read-only, no content actions; excluded from search and indexing).
        createdAt:
          type: integer
          description: Creation timestamp (epoch ms).
        updatedAt:
          type: integer
          description: Update timestamp (epoch ms).
        sizeInBytes:
          type: integer
          nullable: true
          description: File size in bytes for file records; otherwise `null`.
        mimeType:
          type: string
          nullable: true
        extension:
          type: string
          nullable: true
        webUrl:
          type: string
          nullable: true
        hasChildren:
          type: boolean
          description: Whether the node has children (sidebar / tree).
        previewRenderable:
          type: boolean
          nullable: true
        permission:
          type: object
          nullable: true
          description: Per-item permission when `include=permissions` is requested; otherwise `null`.
          required:
          - role
          - canEdit
          - canDelete
          properties:
            role:
              type: string
            canEdit:
              type: boolean
            canDelete:
              type: boolean
        sharingStatus:
          type: string
          nullable: true
          description: |
            Sharing status (e.g. `private`, `shared`, `team`, `workspace`) when
            applicable; otherwise `null`.
    KnowledgeHubNodesResponse:
      type: object
      description: |
        Response body for the Knowledge Hub nodes API. The deployed service
        serialises optional values as JSON `null` and always includes the keys
        listed in `required` (Swagger / clients will see stable shapes, not
        omitted properties).
      required:
      - success
      - error
      - id
      - currentNode
      - parentNode
      - items
      - pagination
      - filters
      - breadcrumbs
      - counts
      - permissions
      - maxFolderDepth
      properties:
        maxFolderDepth:
          type: integer
          description: Deepest a collection folder may be nested; a folder directly in the collection is depth 1.
        success:
          type: boolean
          enum:
          - true
          description: Always `true` on HTTP 200. Failures use 4xx/5xx error envelopes, not this body shape.
        error:
          type: string
          nullable: true
          description: Always `null` on HTTP 200.
        errorCode:
          type: integer
          nullable: true
          description: |
            Status the connector service turns a failed lookup into. Always `null` on HTTP 200:
            a failure is answered with that status and the error envelope instead of this body.
        typed_records:
          type: object
          nullable: true
          description: |
            Full record documents keyed by record ID. Filled only for in-process callers
            (the agent's knowledge navigator); always `null` over HTTP.
          additionalProperties:
            $ref: '#/components/schemas/SemanticSearchGraphRecord'
        id:
          type: string
          nullable: true
          description: Current parent node ID when browsing children; `null` at root.
        currentNode:
          type: object
          nullable: true
          description: Node being browsed when `parentId` is in the path; `null` at root.
          required:
          - id
          - name
          - nodeType
          properties:
            id:
              type: string
            name:
              type: string
            nodeType:
              type: string
              description: One of `app`, `recordGroup`, `folder`, `record`.
            subType:
              type: string
              nullable: true
              description: Connector name or record type when applicable; otherwise `null`.
        parentNode:
          type: object
          nullable: true
          description: |
            Parent of `currentNode` when present; `null` when not applicable,
            and for a connected app whose limit leaves that parent out. For
            such an app, `breadcrumbs` likewise names only the nodes inside
            its limit.
          required:
          - id
          - name
          - nodeType
          properties:
            id:
              type: string
            name:
              type: string
            nodeType:
              type: string
              description: One of `app`, `recordGroup`, `folder`, `record`.
            subType:
              type: string
              nullable: true
        items:
          type: array
          description: Page of nodes for the current browse or search.
          items:
            $ref: '#/components/schemas/KnowledgeHubNode'
        pagination:
          type: object
          required:
          - page
          - limit
          - totalItems
          - totalPages
          - hasNext
          - hasPrev
          properties:
            page:
              type: integer
              nullable: true
              description: Current page (1-indexed). `null` when the request pages by `cursor`.
            limit:
              type: integer
              description: Page size.
            totalItems:
              type: integer
              description: |
                Items in the whole result. For a search by a connected app
                limited to spaces, folders or files, the matches found so far: it can
                grow from page to page and is final once `hasNext` is false.
            totalPages:
              type: integer
              nullable: true
              description: Number of pages. `null` when the request pages by `cursor`.
            hasNext:
              type: boolean
            hasPrev:
              type: boolean
            nextCursor:
              type: string
              nullable: true
              description: Cursor for the next page; null on the last page.
            prevCursor:
              type: string
              nullable: true
              description: Cursor for the previous page; null on the first page.
            startIndex:
              type: integer
              nullable: true
              description: 1-based index of the first item on this page, when known.
            endIndex:
              type: integer
              nullable: true
              description: 1-based index of the last item on this page, when known.
            currentPageItems:
              type: integer
              nullable: true
              description: Number of items on this page.
        filters:
          type: object
          required:
          - applied
          - available
          properties:
            applied:
              type: object
              description: Echo of applied filters; unused slots are JSON `null`.
              required:
              - q
              - nodeTypes
              - recordTypes
              - origins
              - connectorIds
              - indexingStatus
              - createdAt
              - updatedAt
              - size
              - sortBy
              - sortOrder
              properties:
                q:
                  type: string
                  nullable: true
                nodeTypes:
                  type: array
                  nullable: true
                  items:
                    type: string
                recordTypes:
                  type: array
                  nullable: true
                  items:
                    type: string
                origins:
                  type: array
                  nullable: true
                  items:
                    type: string
                connectorIds:
                  type: array
                  nullable: true
                  items:
                    type: string
                indexingStatus:
                  type: array
                  nullable: true
                  items:
                    type: string
                createdAt:
                  nullable: true
                  allOf:
                  - $ref: '#/components/schemas/DateRangeFilter'
                updatedAt:
                  nullable: true
                  allOf:
                  - $ref: '#/components/schemas/DateRangeFilter'
                size:
                  nullable: true
                  allOf:
                  - $ref: '#/components/schemas/SizeRangeFilter'
                sortBy:
                  type: string
                  description: Effective sort field after server normalisation.
                sortOrder:
                  type: string
                  description: Effective sort order after server normalisation.
            available:
              type: object
              nullable: true
              description: Populated when `include=availableFilters`; otherwise `null`.
              required:
              - nodeTypes
              - recordTypes
              - origins
              - connectors
              - indexingStatus
              - sortBy
              - sortOrder
              properties:
                nodeTypes:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                recordTypes:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                origins:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                connectors:
                  type: array
                  description: |
                    The apps and collections to filter by, each with its own name. For a
                    connected app with a limit, only those the limit covers whole: an app
                    or collection it covers only in part (some of its spaces, folders or
                    files) is not offered. The other option lists are fixed and name no
                    source.
                  items:
                    $ref: '#/components/schemas/FilterOption'
                indexingStatus:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                sortBy:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
                sortOrder:
                  type: array
                  items:
                    $ref: '#/components/schemas/FilterOption'
        breadcrumbs:
          type: array
          nullable: true
          description: Present when `include=breadcrumbs`; otherwise `null`.
          items:
            type: object
            required:
            - id
            - name
            - nodeType
            properties:
              id:
                type: string
              name:
                type: string
              nodeType:
                type: string
                description: One of `app`, `recordGroup`, `folder`, `record`.
              subType:
                type: string
                nullable: true
        counts:
          type: object
          nullable: true
          description: Present when `include=counts`; otherwise `null`.
          required:
          - items
          - total
          properties:
            items:
              type: array
              items:
                type: object
                required:
                - label
                - count
                properties:
                  label:
                    type: string
                  count:
                    type: integer
            total:
              type: integer
        permissions:
          type: object
          nullable: true
          description: Present when `include=permissions`; otherwise `null`.
          required:
          - role
          - canUpload
          - canCreateFolders
          - canEdit
          - canDelete
          - canManagePermissions
          properties:
            role:
              type: string
            canUpload:
              type: boolean
            canCreateFolders:
              type: boolean
            canEdit:
              type: boolean
            canDelete:
              type: boolean
            canManagePermissions:
              type: boolean
            collectionRole:
              type: string
              nullable: true
              description: |
                The caller's own role on the collection (knowledge base) this node is in, as
                restore and `GET /knowledgeBase/{kbId}/trash` check it: OWNER, WRITER,
                FILEORGANIZER, COMMENTER or READER. Unlike `role`, which ranks record
                permissions inside a folder, it is the same at every level of the collection.
                Null outside a collection.
    AgentCapabilities:
      type: object
      additionalProperties: false
      description: |
        Per-request agent capability toggles. Only meaningful when `chatMode`
        selects an agent mode; ignored otherwise. Each field falls back to its
        own `default` below when omitted — a missing flag is not uniformly
        `true`. Omitting the whole object applies every default.
      properties:
        internalSearch:
          type: boolean
          default: true
          description: Whether the agent may search internal knowledge bases for this turn.
        webSearch:
          type: boolean
          default: true
          description: Whether the agent may perform web search for this turn.
        deepSearch:
          type: boolean
          default: false
          description: Whether the agent may use deeper, higher-latency retrieval for this turn.
    Filters:
      type: object
      additionalProperties: false
      description: |
        What retrieval is narrowed to for a turn: whole apps, and selections below app
        level (record groups, folders, records). The keys are a union. For **org assistant**
        chat streams, send explicit lists. For **agent** chat streams, send explicit id lists,
        or **omit** `filters` (and `tools`) to let the service use the agent’s stored knowledge
        and tool configuration. Sending `{ "apps": [], "kb": [] }` on an agent stream means
        **no** knowledge sources for that turn (it is not “full org default”).

        A selection below app level is the whole scope of the turn: with `recordGroups`,
        `records` or `recordsExact` present, an absent or empty `apps` / `kb` means none of
        them. A selected node that does not exist or that the caller cannot read contributes
        nothing; when nothing valid remains the turn searches nothing. `/search` answers 404
        for that; a chat turn is not failed, its search simply finds nothing.
        At most 200 ids may be sent in one request, counted across all keys, and every id must
        be a valid UUID. A key this schema does not list is refused with 400; the message names
        the key and lists the allowed ones. A value of the wrong type is refused with 400 too.

        A selection that covers more than the configured number of nodes (50,000 by default),
        or that touches a source still being prepared for folder-level search, is refused:
        `/search` and the non-streaming chat routes answer 422 with the message, and a chat
        stream ends with an error frame (`RUN_ERROR`, or `error` on the legacy protocol)
        whose `code` is `selection_too_large` or `selection_not_ready` and whose `message`
        says what to change. No model call is made for such a turn.
      properties:
        apps:
          type: array
          items:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: |
            Whole apps: connector instance ids and collection (knowledge base) ids.
            Each element must be a valid UUID.
        kb:
          type: array
          items:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: |
            Older name for collection ids; treated the same as `apps`.
            Each element must be a valid UUID.
        recordGroups:
          type: array
          items:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: |
            Record group ids (a drive, a space, a project). Each selects the group, the
            groups nested in it and every record that belongs to them.
            Each element must be a valid UUID.
        records:
          type: array
          items:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: |
            Folder or record ids. Each selects the node and everything under it
            (child items and attachments).
            Each element must be a valid UUID.
        recordsExact:
          type: array
          items:
            type: string
            pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: |
            Record ids selected alone, without what is under them.
            Each element must be a valid UUID.
        entityFilters:
          type: object
          additionalProperties: false
          x-pipeshub-stability: experimental
          description: |
            **Experimental** named-entity constraints (Labs flag `ENABLE_NAMED_ENTITY_EXTRACTION`, or `HIGH_ACCURACY_MODE`).
            Every constraint must hold for the same record: an amount and a date match a record
            that mentions both, not one entity that is both. `name`/`entityIds` match entity nodes;
            `mentionedDate`, `amount`, `quantity` and `percent` match typed values the record
            mentions (any date mentioned, not a role such as "signed on"). A kind of a typed
            constraint's own kind narrows it (`currency` with `amount`); other kinds are a
            constraint of their own. Only records the caller may read are considered: every empty
            result reads the same.

            An unusable filter (unknown kind, bad currency, a range whose low end is above its high
            end, or a blank name) fails request validation with 400, including on conversation
            requests. On `POST /search`, a valid filter matching too many readable records is
            refused with 422. Conversation operations apply a valid filter to every search behind
            the answer; if retrieval refuses it, the request does not fail and the answer says why
            the filter could not be applied.
          properties:
            kinds:
              type: array
              minItems: 1
              maxItems: 23
              description: Lowercase, as listed. The server trims and lowercases each kind before checking it.
              items:
                title: NamedEntityKind
                type: string
                enum:
                - person
                - person_type
                - organization
                - event
                - product
                - skill
                - location
                - city
                - state
                - country_region
                - address
                - date
                - date_range
                - date_time
                - duration
                - currency
                - percentage
                - age
                - dimension
                - email
                - url
                - phone
                - ip
            name:
              type: string
              minLength: 1
              maxLength: 256
              description: Case-insensitive prefix of an entity name; surrounding blanks are trimmed and a blank name is refused.
            entityIds:
              type: array
              minItems: 1
              maxItems: 100
              items:
                type: string
                format: uuid
              description: Entity node ids, as returned by entity search. Typed values have no id.
            mentionedDate:
              type: object
              additionalProperties: false
              description: Overlap with a date the record mentions; half-open, `from` must not be after `to`.
              properties:
                from:
                  oneOf:
                  - type: integer
                    description: Epoch milliseconds.
                  - type: string
                    description: ISO-8601 date or date-time; a date alone is UTC midnight.
                to:
                  oneOf:
                  - type: integer
                    description: Epoch milliseconds.
                  - type: string
                    description: ISO-8601 date or date-time; a date alone is UTC midnight.
            amount:
              type: object
              additionalProperties: false
              description: '`min` must not be after `max`.'
              properties:
                min:
                  type: number
                max:
                  type: number
                currency:
                  type: string
                  pattern: ^[A-Za-z]{3}$
                  description: ISO 4217 code, case-insensitive.
            quantity:
              type: object
              additionalProperties: false
              description: In SI units of the dimension. `min` must not be after `max`.
              properties:
                min:
                  type: number
                max:
                  type: number
                dimension:
                  type: string
                  pattern: ^[A-Za-z_]{1,32}$
                  description: For example `length`, `weight`, `speed`, `temperature`, `age`.
            percent:
              type: object
              additionalProperties: false
              description: Fractions (0.125 is 12.5%). `min` must not be after `max`.
              properties:
                min:
                  type: number
                max:
                  type: number
        where:
          description: Reserved for the typed filter tree that will replace `entityFilters`; any value is refused with 400.
          not: {}
          x-speakeasy-ignore: true
    AppliedFilterNode:
      type: object
      additionalProperties: false
      description: |
        A single filter node selected by the user (used for display/persistence of active
        filters). The gateway refuses a node that lacks any of the four fields.
      required:
      - id
      - name
      - nodeType
      - connector
      properties:
        id:
          type: string
          description: Unique identifier of the filter node
        name:
          type: string
          description: Display name of the filter node
        nodeType:
          type: string
          description: Type of the node (e.g. app, recordGroup, folder, record)
        connector:
          type: string
          description: Connector identifier associated with this node
        extension:
          type: string
          description: File extension of a record node, for its icon
        mimeType:
          type: string
          description: MIME type of a record node, for its icon
        mentioned:
          type: boolean
          description: True when the node was picked with an @ mention in the message
    AppliedFilters:
      type: object
      additionalProperties: false
      description: |
        Rich filter state selected by the user, used for display and persistence only.
        This mirrors the active selection shown in the UI and is distinct from the
        machine-readable `filters` field used for retrieval scoping.
      properties:
        apps:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/AppliedFilterNode'
            - $ref: '#/components/schemas/RedactedSource'
          description: Applied app/connector filter nodes
        kb:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/AppliedFilterNode'
            - $ref: '#/components/schemas/RedactedSource'
          description: Applied knowledge-base filter nodes
        recordGroups:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/AppliedFilterNode'
            - $ref: '#/components/schemas/RedactedSource'
          description: Applied record-group filter nodes
        records:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/AppliedFilterNode'
            - $ref: '#/components/schemas/RedactedSource'
          description: Applied folder and record filter nodes (each with everything under it)
        recordsExact:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/AppliedFilterNode'
            - $ref: '#/components/schemas/RedactedSource'
          description: Applied record filter nodes selected alone
    ChatAttachmentRef:
      type: object
      additionalProperties: false
      description: |
        Reference to an attachment produced by `POST /conversations/attachments/upload`
        (or the equivalent agent route). Include in create/stream/message bodies
        so the turn is sent with uploaded files.
      required:
      - recordId
      properties:
        recordId:
          type: string
          minLength: 1
          description: Attachment record id returned from the upload endpoint.
        recordName:
          type: string
          minLength: 1
          description: Original display name of the file when known.
        mimeType:
          type: string
          minLength: 1
          description: MIME type of the uploaded file.
        extension:
          type: string
          minLength: 1
          description: File extension (e.g. `pdf`).
        virtualRecordId:
          type: string
          minLength: 1
          description: Optional synthetic record id used by the graph layer.
        source:
          type: string
          enum:
          - upload
          - paste-text
          description: |
            How the attachment was produced: a file upload, or text pasted into the
            composer and sent as a file. Stored on the saved message as sent.
    ChatAttachmentUploadRef:
      type: object
      additionalProperties: false
      description: |
        Concrete attachment metadata returned by `POST /conversations/attachments/upload`
        (or the equivalent agent route).
      required:
      - recordId
      - recordName
      - mimeType
      - extension
      - virtualRecordId
      properties:
        recordId:
          type: string
          minLength: 1
          description: Server-assigned attachment record id.
        recordName:
          type: string
          minLength: 1
          description: Original filename stored for the attachment.
        mimeType:
          type: string
          minLength: 1
          description: |
            MIME type of the stored file. For an image whose bytes are a JPEG or a PNG it is
            `image/jpeg` or `image/png` as the bytes say, whatever type was declared; other
            files keep the declared type. Files, images included, are stored as sent.
        extension:
          type: string
          minLength: 1
          description: File extension derived by the backend.
        virtualRecordId:
          type: string
          minLength: 1
          description: Synthetic record id used by the graph layer.
        parseMode:
          type: string
          minLength: 1
          description: Backend-reported parsing mode used for the attachment (e.g. `pdfplumber`, `docling`, `csv_lightweight`).
        ocrMode:
          type: string
          minLength: 1
          deprecated: true
          description: Deprecated alias for `parseMode`, kept for backward compatibility. Use `parseMode` instead.
    ChatAttachmentUploadResponse:
      type: object
      additionalProperties: false
      description: |
        Success envelope returned by `POST /conversations/attachments/upload`
        and `POST /agents/{agentKey}/conversations/attachments/upload`.
      required:
      - conversationId
      - attachments
      properties:
        conversationId:
          type: string
          nullable: true
          description: |
            Existing conversation id echoed from the request when the upload is tied to a thread; otherwise `null`.
        attachments:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ChatAttachmentUploadRef'
    CreateConversationRequest:
      type: object
      description: |
        Request body for creating a new AI conversation.

        **Query Processing:**

        The query is processed through PipesHub's AI pipeline which:

        - Performs semantic search across indexed knowledge bases
        - Retrieves relevant context from matching documents
        - Generates a response with citations to source materials
        - Suggests follow-up questions based on the conversation

        **History:** a new conversation starts with no history, and
        history is never accepted from the caller. A body carrying
        `previousConversations` with any value but an empty list (`null`, a
        string or an object included) is rejected with 400; an empty list is
        dropped. Send follow-up questions to
        `POST /conversations/{conversationId}/messages`; the server replays
        the stored conversation.

        Fields not listed here are dropped by the gateway's validator, not refused.
      required:
      - query
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 100000
          description: |
            The user's question or prompt to start the conversation.
            Supports natural language queries of any complexity.
          example: What are the key findings from our Q4 financial report?
        recordIds:
          type: array
          items:
            type: string
            format: objectId
            pattern: ^[0-9a-fA-F]{24}$
          description: |
            Limit the AI's knowledge scope to specific records/documents.
            When provided, only these records will be searched for context.
          example:
          - 507f1f77bcf86cd799439011
          - 507f1f77bcf86cd799439012
        filters:
          $ref: '#/components/schemas/Filters'
        appliedFilters:
          $ref: '#/components/schemas/AppliedFilters'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ChatAttachmentRef'
          description: |
            Uploaded chat attachments to associate with this conversation turn (see
            `POST /conversations/attachments/upload`).
        projectId:
          type: string
          format: objectId
          pattern: ^[0-9a-fA-F]{24}$
          description: |
            Link the new conversation to a project the caller has at least
            viewer access to. When the project's instructions, knowledge
            scope, or files are set and this request didn't supply its own
            `filters`/`attachments`, they are merged in as a fallback (the
            request always wins). Ignored on follow-up turns — only
            meaningful when creating a conversation.
            An OAuth token or PAT also needs `project:read`. An archived
            project answers `409`; a project the caller cannot see, `404`,
            before any stream opens.
        projectVisibility:
          type: string
          enum:
          - private
          - project
          description: |
            Only meaningful together with `projectId`. Overrides the
            project's default sharing behavior for this one conversation:
            `private` keeps it visible to the owner only; `project` exposes
            it to every project member. Defaults from the project's
            `chatSharing` setting when omitted.
        modelKey:
          type: string
          minLength: 1
          description: |
            Identifier for the AI model configuration to use.
            Available models depend on organization settings. When neither
            `modelKey` nor `modelName` is sent, the organization's default
            model answers and is saved in the conversation's `modelInfo`.
            A key that matches no configured model is not refused: the
            default model answers, and the unknown key is still saved in
            `modelInfo`.
          example: gpt-5.6-luna
        modelName:
          type: string
          minLength: 1
          description: Display name of the AI model
          example: gpt-5.6-luna
        modelFriendlyName:
          type: string
          minLength: 1
          description: Friendly display name of the selected model
          example: gpt-5.6-Luna
        chatMode:
          type: string
          enum:
          - agent
          - internal_search
          - web_search
          - deep
          - quick
          - verification
          - auto
          description: |
            Optional execution mode for non-stream consumers of this shared
            request schema. `deep`, `quick`, `verification` and `auto` are
            legacy values: still accepted, they run as `internal_search`.
            The streaming routes accept only `agent`, `internal_search` and
            `web_search`. `agent:<mode>` is refused.
            `agent` uses the universal agent loop, while `internal_search`
            and `web_search` use their corresponding assistant search paths.
          example: internal_search
        timezone:
          type: string
          minLength: 1
          description: |
            IANA timezone identifier from the client (top-level field).
            Used to provide time-aware context to the AI.
          example: America/New_York
        currentTime:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$
          description: |
            ISO 8601 / RFC 3339 datetime from the client (top-level field; UTC `Z` or numeric offset).
          example: '2026-04-12T16:00:00+05:30'
        tools:
          type: array
          items:
            type: string
            minLength: 1
          description: |
            Optional list of tool identifiers (fully-qualified action names such as
            "jira.create_issue") that the AI agent is permitted to invoke for this
            request. When omitted the agent may use any configured tool. Applicable
            only when `chatMode` is `agent`. Web search is not governed by this
            list; `agentCapabilities.webSearch` turns it on or off.
          example:
          - jira.create_issue
          - confluence.search_content
        protocol:
          type: string
          enum:
          - agui
          description: |
            AG-UI is the only supported wire protocol. When present must be
            `"agui"`. Omitting the field is equivalent — the server always
            uses the AG-UI vocabulary (`RUN_STARTED`, `TEXT_MESSAGE_CONTENT`,
            etc.). Kept in the schema for backward compatibility with callers
            that already send it.
        agentCapabilities:
          $ref: '#/components/schemas/AgentCapabilities'
        includeRetrievalContext:
          type: boolean
          default: false
          description: 'Opt in to measurement frames on this stream: CUSTOM `retrieval_context` events naming the records and blocks that reached the model, and one CUSTOM `run_usage` event carrying the run''s token totals and loop outcome. Identifiers only, never block text. Does not change the answer.'
        keywordSearchBudget:
          type: string
          enum:
          - short
          - full
          description: How long each search waits for the keyword (grep) match after its semantic results are in. `short` waits at most 5 seconds and keeps the keyword matches found by then, for callers that would rather answer sooner, such as agents calling chat over MCP. `full`, or leaving it out, waits for all of it. Deployments running `HIGH_ACCURACY_MODE` always wait in full.
        toolApproval:
          $ref: '#/components/schemas/ToolApprovalAnswer'
        runId:
          type: string
          format: uuid
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: |
            Client-generated identifier for this run. Send it here to enable
            `POST /conversations/{conversationId}/cancel {runId}` while the
            stream is still generating. Optional — a caller that never sends
            one just can't cooperatively cancel the run.
        reasoningEffort:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: |
            How hard a reasoning model should think for this turn. Saved in
            the conversation's `modelInfo`.
    ConversationStreamRequest:
      allOf:
      - $ref: '#/components/schemas/CreateConversationRequest'
      - type: object
        description: |
          Request body for `POST /conversations/stream`. The public stream
          requires an explicit universal execution mode; the legacy modes
          the non-streaming route accepts are refused here. Unlike
          `POST /conversations/create`, a `query` of only whitespace is not
          refused: the turn runs and the conversation is titled with it.
        required:
        - chatMode
        properties:
          chatMode:
            type: string
            enum:
            - agent
            - internal_search
            - web_search
    CreateAgentConversationResponse:
      type: object
      description: |
        Envelope returned by `POST /agents/{agentKey}/conversations`: the
        persisted agent conversation (initial user message plus the agent's
        answer) and request metadata.
      required:
      - conversation
      - meta
      properties:
        conversation:
          $ref: '#/components/schemas/AgentConversation'
        meta:
          type: object
          required:
          - timestamp
          - duration
          properties:
            requestId:
              type: string
            timestamp:
              type: string
              format: date-time
            duration:
              type: integer
              minimum: 0
    CreateConversationResponse:
      type: object
      additionalProperties: false
      description: |
        Envelope returned by `POST /conversations/create`. Contains the
        persisted conversation (including the initial user message and the AI
        response) plus request metadata.
      required:
      - conversation
      - meta
      properties:
        conversation:
          $ref: '#/components/schemas/Conversation'
        meta:
          type: object
          additionalProperties: false
          required:
          - timestamp
          - duration
          properties:
            requestId:
              type: string
              description: |
                Request correlation id. Omitted when upstream middleware did
                not set a request id on the context.
            timestamp:
              type: string
              format: date-time
              description: Server timestamp when the response was sent.
            duration:
              type: integer
              minimum: 0
              description: Total handler duration in milliseconds.
    AgentStreamCreateConversationRequest:
      allOf:
      - $ref: '#/components/schemas/AgentCreateConversationRequest'
      - type: object
        description: |
          Request body for `POST /agents/{agentKey}/conversations/stream`.
          `query` and `chatMode: quick` are required; all other fields are
          optional overrides. Unknown fields are stripped during validation.
          Unlike the non-streaming route, a `query` of only whitespace is
          accepted and starts a conversation.
        required:
        - chatMode
    AgentCreateConversationRequest:
      type: object
      additionalProperties: false
      description: |
        First turn of an agent conversation. Used as-is by the non-streaming
        `POST /agents/{agentKey}/conversations`, where `chatMode` may be
        omitted; `AgentStreamCreateConversationRequest` additionally requires
        it. Unknown fields are stripped during validation, except
        `previousConversations`: history is never accepted from the caller,
        so `previousConversations` with any value but an empty list (`null`,
        a string or an object included) is rejected with 400; an empty list
        is dropped. Follow-up turns go to
        `POST /agents/{agentKey}/conversations/{conversationId}/messages`,
        where the server replays the stored conversation.
      required:
      - query
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 100000
          description: |
            User prompt for the first turn. Saved as the initial `user_query`
            message and sent to the agent backend.
        recordIds:
          type: array
          items:
            type: string
            format: objectId
            pattern: ^[0-9a-fA-F]{24}$
          description: |
            Optional record ids to include as context for this turn. Each id
            must be a 24-character MongoDB ObjectId.
        filters:
          allOf:
          - $ref: '#/components/schemas/Filters'
          description: |
            Optional retrieval scope (`apps` / `kb`) for this turn. Each id must
            be a valid UUID. Omit for agent defaults; send `{ "apps": [], "kb": [] }`
            to force no knowledge sources for this turn.
        appliedFilters:
          allOf:
          - $ref: '#/components/schemas/AppliedFilters'
          description: |
            UI filter state persisted on the saved user message. Not used for
            retrieval and not forwarded to the upstream agent backend.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ChatAttachmentRef'
          description: |
            Uploaded attachments to ground this turn. Each entry references a
            record id returned from the agent attachment upload endpoint.
        projectId:
          type: string
          format: objectId
          pattern: ^[0-9a-fA-F]{24}$
          description: |
            Link the new agent conversation to a project the caller has at
            least viewer access to. Same fallback/merge semantics as
            `POST /conversations/create`. Ignored on follow-up turns — the
            session row is the source of truth once the conversation exists.
            An OAuth token or PAT also needs `project:read`. An archived
            project answers `409`; a project the caller cannot see, `404`,
            before any stream opens.
        projectVisibility:
          type: string
          enum:
          - private
          - project
          description: |
            Only meaningful together with `projectId`. Overrides the
            project's default sharing behavior for this one conversation.
        chatMode:
          type: string
          enum:
          - quick
          description: |
            Execution mode. Scoped agent conversations support only `quick`.
            Required on the `/stream` route; optional on the non-streaming
            route.
        modelKey:
          type: string
          minLength: 1
          description: |
            AI model configuration id for this turn. Omit to use the agent's
            default model. A key that names no configured model is not refused:
            the turn runs on the organization's default model and the unknown
            key is still stored in the conversation's `modelInfo`.
        modelName:
          type: string
          minLength: 1
          description: Provider model name (the underlying LLM identifier).
        modelFriendlyName:
          type: string
          minLength: 1
          description: Friendly UI label for the selected model.
        timezone:
          type: string
          minLength: 1
          description: |
            Client IANA timezone, such as `America/New_York`. Helps the agent
            resolve relative date references in the prompt.
        currentTime:
          type: string
          format: date-time
          pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$
          description: |
            Client time in ISO 8601 / RFC 3339 format (UTC `Z` or numeric
            offset). Sent alongside `timezone` for time-aware answers.
        tools:
          type: array
          items:
            type: string
            minLength: 1
          description: |
            Allowed tool ids for this turn, such as `jira.create_issue`. Omit
            to let the agent use its default toolset; send `[]` to disable
            tools for this turn. A list that leaves out `web_search` turns off
            the agent's web search for the turn.
        protocol:
          type: string
          enum:
          - agui
          description: |
            AG-UI is the only supported wire protocol. When present must be
            `"agui"`. Omitting the field is equivalent — the server always
            uses the AG-UI vocabulary (see `AgentStreamSSEEvent`). Kept in
            the schema for backward compatibility with callers that already
            send it.
        agentCapabilities:
          $ref: '#/components/schemas/AgentCapabilities'
        includeRetrievalContext:
          type: boolean
          default: false
          description: 'Opt in to measurement frames on this stream: CUSTOM `retrieval_context` events naming the records and blocks that reached the model, and one CUSTOM `run_usage` event carrying the run''s token totals and loop outcome. Identifiers only, never block text. Does not change the answer.'
        keywordSearchBudget:
          type: string
          enum:
          - short
          - full
          description: How long each search waits for the keyword (grep) match after its semantic results are in. `short` waits at most 5 seconds and keeps the keyword matches found by then, for callers that would rather answer sooner, such as agents calling chat over MCP. `full`, or leaving it out, waits for all of it. Deployments running `HIGH_ACCURACY_MODE` always wait in full.
        toolApproval:
          $ref: '#/components/schemas/ToolApprovalAnswer'
        runId:
          type: string
          format: uuid
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: |
            Client-generated identifier for this run. Send it here to enable
            `POST /agents/{agentKey}/conversations/{conversationId}/cancel
            {runId}` while the stream is still generating.
        reasoningEffort:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: |
            Reasoning effort for this turn, for models that support it. Stored on
            the conversation's model info and forwarded to the AI backend.
      example:
        query: what are some latest tech news?
        modelKey: 5c1832f4-fa19-4167-b913-307fad3a6551
        modelName: gpt-5.6-luna
        modelFriendlyName: GPT 5.4 mini
        chatMode: quick
        timezone: Asia/Kolkata
        currentTime: '2026-05-19T12:58:01+05:30'
        tools: []
        filters:
          apps:
          - 2605c882-61d4-4aa2-b480-a68c957c151d
          - ed6d6cc4-70bd-4838-9aeb-488e910c833a
          - aeab9ddc-fb9b-47c8-ad98-bd4744e19555
          kb:
          - 8747da12-4724-4a95-ac92-827b88d79647
        appliedFilters:
          apps:
          - id: 2605c882-61d4-4aa2-b480-a68c957c151d
            name: US Headlines, abcnews
            nodeType: app
            connector: RSS
          - id: ed6d6cc4-70bd-4838-9aeb-488e910c833a
            name: ABC News RSS
            nodeType: app
            connector: RSS
          - id: aeab9ddc-fb9b-47c8-ad98-bd4744e19555
            name: Hacker news rss
            nodeType: app
            connector: RSS
          kb:
          - id: 8747da12-4724-4a95-ac92-827b88d79647
            name: Siddhant Ota's Private
            nodeType: recordGroup
            connector: KB
    RegenerateRequest:
      type: object
      additionalProperties: false
      description: |
        Request body for regenerating an AI response. All fields are optional;
        when omitted the model selection and execution context from the
        original message are reused.

        Supported fields:
        - `attachments` — optional files of the edited question, replacing the
          stored ones (an empty list removes them all); omitted keeps them.
          At most 10, each a ref from the attachment upload
        - `query` — optional edited question. When it differs from the stored
          question, the answer is regenerated for it and the stored question is
          replaced once the new answer is saved; a failed run keeps the original
        - `filters` — optional `{ apps?, kb? }` filter object
        - `chatMode` — optional non-empty chat mode string
        - `modelKey`, `modelName`, `modelFriendlyName` —
          optional non-empty model override fields
        - `timezone` — optional non-empty client timezone string
        - `currentTime` — optional ISO 8601 / RFC 3339 datetime string with
          UTC `Z` or a numeric offset
        - `tools` — optional array of non-empty tool identifiers
        - `protocol` — optional inert compatibility field; when present it must
          be `agui`, which is also the protocol used when the field is omitted
        - `agentCapabilities` — optional per-request agent capability toggles
        - `answers` — optional changed answers to the question card the reply
          followed; the turn is re-run with them and they replace the saved ones
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 100000
          description: |
            The edited question to answer in place of the stored one. Only the
            last question of a conversation can be edited, and not one that ran
            an approved action or is itself a tool-approval or question-card
            answer. A turn that went through an answered question card can be
            edited: the question is rewritten and the whole turn, including its
            card and the card's answers, is replaced by the new answer. A card
            turn that spans more than 50 saved rows cannot be edited; the
            request is refused and the stored answer is left as it was. So is
            an edit of an older question while a newer question has no answer.
            A run that ends in an error answer, or whose answer cannot be
            saved, leaves the stored question, its files and the rows of its
            card turn as they were.
        attachments:
          type: array
          maxItems: 10
          items:
            $ref: '#/components/schemas/ChatAttachmentRef'
          description: |
            The files of the edited question, replacing the stored ones. An
            empty list removes them all; omitted keeps the stored files. A
            change of files alone, with the same `query`, also counts as an
            edit. Files are not deleted when removed from a question: a fork
            of the chat may still refer to them.
        filters:
          $ref: '#/components/schemas/Filters'
        answers:
          type: string
          maxLength: 8000
          pattern: '^\s*User selections:'
          description: |
            The answers to the question card this reply followed, in the form
            the app sends them (`User selections:` followed by one
            `N. "question" → answer` line each). When present, the turn is
            re-run with these answers instead of the saved ones, and they are
            saved in their place. Over 8000 characters, or text not starting with
            `User selections:`, is refused with `400 VALIDATION_ERROR`. A reply
            that did not follow a question card, or a request that also edits
            the question (`query` or `attachments`), is refused after the stream
            opens: a 200 stream ending in a `RUN_ERROR` (see the operation).
          example: |-
            User selections:
            1. "Which region?" → EU
        modelKey:
          type: string
          minLength: 1
          description: |
            Identifier of the AI model configuration to use for regeneration.
            Typically a UUID returned by the model-management endpoints. When
            omitted, the model used for the original message is reused.
          example: 05438a37-68f2-4641-a8dc-6c47e63278ca
        modelName:
          type: string
          minLength: 1
          description: Provider model name (e.g. the underlying LLM identifier).
          example: gpt-5.6-luna
        modelFriendlyName:
          type: string
          minLength: 1
          description: Friendly display name of the selected model.
          example: mini
        chatMode:
          type: string
          minLength: 1
          description: |
            Chat mode used for regeneration (for example `internal_search`,
            `web_search`, or the universal `agent` mode).
          example: internal_search
        reasoningEffort:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: |
            Reasoning effort for this turn, for models that support it. Stored on
            the conversation's model info and forwarded to the AI backend.
        timezone:
          type: string
          minLength: 1
          description: |
            IANA timezone identifier from the client. Used to provide
            time-aware context to the AI during regeneration.
          example: Asia/Calcutta
        currentTime:
          type: string
          format: date-time
          pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$
          description: |
            ISO 8601 / RFC 3339 datetime from the client (UTC `Z` or numeric
            offset). Used to anchor any relative time references in the query.
          example: '2026-05-11T15:43:21+05:30'
        tools:
          type: array
          items:
            type: string
            minLength: 1
          description: |
            Optional list of tool identifiers (fully-qualified action names
            such as `jira.create_issue`) the agent may invoke when
            regenerating. Applicable only in agent chat modes. Regenerating
            in the assistant's agent mode, web search is not governed by this
            list; `agentCapabilities.webSearch` turns it on or off.
            Regenerating a named agent's message (`AgentRegenerateRequest`),
            a list that leaves out `web_search` turns off the agent's web
            search for the turn, even when `agentCapabilities.webSearch` is
            true.
          example:
          - jira.create_issue
          - confluence.search_content
        protocol:
          type: string
          enum:
          - agui
          description: |
            AG-UI is the only supported wire protocol. When present must be
            `"agui"`. Omitting the field is equivalent — the server always
            uses the AG-UI vocabulary. Kept in the schema for backward
            compatibility with callers that already send it.
        agentCapabilities:
          $ref: '#/components/schemas/AgentCapabilities'
        toolApproval:
          $ref: '#/components/schemas/ToolApprovalAnswer'
        runId:
          type: string
          format: uuid
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: |
            Client-generated identifier for this regeneration run. Send it
            here to enable `POST .../cancel {runId}` while it is still
            generating.
    AgentRegenerateRequest:
      allOf:
      - $ref: '#/components/schemas/RegenerateRequest'
      - type: object
        description: |
          Regeneration payload for a scoped agent conversation. The public
          gateway requires `chatMode: quick`; all other fields retain the
          semantics defined by `RegenerateRequest`.
        required:
        - chatMode
        properties:
          chatMode:
            type: string
            enum:
            - quick
    AddMessageRequest:
      type: object
      description: |
        Request body for adding a message to an existing conversation.
        Fields not listed here are dropped by the gateway's validator, not refused.
      required:
      - query
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 100000
          description: |
            The follow-up question or message content. Held to the same
            100,000-character limit as the first message of a conversation.
          example: Can you elaborate on the revenue trends?
        filters:
          $ref: '#/components/schemas/Filters'
        appliedFilters:
          $ref: '#/components/schemas/AppliedFilters'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ChatAttachmentRef'
          description: |
            Uploaded chat attachments for this follow-up turn (see
            `POST /conversations/attachments/upload`).
        modelKey:
          type: string
          minLength: 1
          description: |
            Override the model for this specific message. When neither
            `modelKey` nor `modelName` is sent, the organization's default
            model answers and is saved in the message's `modelInfo`.
        modelName:
          type: string
          minLength: 1
          description: Display name of the model
        modelFriendlyName:
          type: string
          minLength: 1
          description: Friendly display name of the model
        chatMode:
          type: string
          enum:
          - agent
          - internal_search
          - web_search
          - deep
          - quick
          - verification
          - auto
          description: |
            Optional execution mode for non-stream consumers of this shared
            request schema. `deep`, `quick`, `verification` and `auto` are
            legacy values: still accepted, they run as `internal_search`.
            The streaming routes accept only `agent`, `internal_search` and
            `web_search`. `agent:<mode>` is refused.
        timezone:
          type: string
          minLength: 1
          description: |
            IANA timezone identifier from the client (top-level field).
            Used to provide time-aware context to the AI.
          example: America/New_York
        currentTime:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$
          description: |
            ISO 8601 / RFC 3339 datetime from the client (top-level field; UTC `Z` or numeric offset).
          example: '2026-04-12T16:00:00+05:30'
        tools:
          type: array
          items:
            type: string
            minLength: 1
          description: |
            Optional list of tool identifiers the agent may invoke for this
            follow-up message. Semantics are identical to the create-conversation
            tools field.
          example:
          - jira.create_issue
          - confluence.search_content
        protocol:
          type: string
          enum:
          - agui
          description: |
            AG-UI is the only supported wire protocol. When present must be
            `"agui"`. Omitting the field is equivalent — the server always
            uses the AG-UI vocabulary (see `ConversationMessageStreamSSEEvent`).
            Kept in the schema for backward compatibility with callers that
            already send it.
        agentCapabilities:
          $ref: '#/components/schemas/AgentCapabilities'
        includeRetrievalContext:
          type: boolean
          default: false
          description: 'Opt in to measurement frames on this stream: CUSTOM `retrieval_context` events naming the records and blocks that reached the model, and one CUSTOM `run_usage` event carrying the run''s token totals and loop outcome. Identifiers only, never block text. Does not change the answer.'
        keywordSearchBudget:
          type: string
          enum:
          - short
          - full
          description: How long each search waits for the keyword (grep) match after its semantic results are in. `short` waits at most 5 seconds and keeps the keyword matches found by then, for callers that would rather answer sooner, such as agents calling chat over MCP. `full`, or leaving it out, waits for all of it. Deployments running `HIGH_ACCURACY_MODE` always wait in full.
        toolApproval:
          $ref: '#/components/schemas/ToolApprovalAnswer'
        runId:
          type: string
          format: uuid
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: |
            Client-generated identifier for this run. Send it here to enable
            `POST /conversations/{conversationId}/cancel {runId}` while the
            stream is still generating.
        reasoningEffort:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: |
            How hard a reasoning model should think for this turn. Saved in
            the conversation's `modelInfo`.
    ConversationMessageStreamRequest:
      allOf:
      - $ref: '#/components/schemas/AddMessageRequest'
      - type: object
        description: |
          Request body for
          `POST /conversations/{conversationId}/messages/stream`. The public
          stream requires an explicit universal execution mode; the legacy
          modes the non-streaming route accepts are refused here. Unlike the
          non-streaming route, a `query` of only whitespace is not refused:
          the turn runs with it.
        required:
        - chatMode
        properties:
          chatMode:
            type: string
            enum:
            - agent
            - internal_search
            - web_search
    AddMessageResponse:
      type: object
      additionalProperties: false
      description: |
        Envelope returned by `POST /conversations/{conversationId}/messages`.
        Contains the updated conversation, the number of citation records used
        to ground the AI response for this turn, and request metadata.
      required:
      - conversation
      - recordsUsed
      - meta
      properties:
        conversation:
          $ref: '#/components/schemas/Conversation'
        recordsUsed:
          type: integer
          minimum: 0
          description: |
            Number of citation records used to ground the AI response generated
            for this turn.
        meta:
          type: object
          additionalProperties: false
          required:
          - timestamp
          - duration
          properties:
            requestId:
              type: string
              description: |
                Request correlation id. Omitted when upstream middleware did
                not set `req.context.requestId`.
            timestamp:
              type: string
              format: date-time
              description: Server timestamp when the response was sent.
            duration:
              type: integer
              minimum: 0
              description: Total handler duration in milliseconds.
            recordsUsed:
              type: integer
              minimum: 0
              description: |
                Same value as the top-level `recordsUsed`. Duplicated inside
                `meta` for client convenience.
    AgentAddMessageStreamRequest:
      allOf:
      - $ref: '#/components/schemas/AgentAddMessageRequest'
      - type: object
        description: |
          Request body for `POST /agents/{agentKey}/conversations/{conversationId}/messages/stream`.
          `query` and `chatMode: quick` are required; all other fields are
          optional overrides. Unknown fields are stripped during validation.
        required:
        - chatMode
    AgentAddMessageRequest:
      type: object
      additionalProperties: false
      description: |
        Follow-up turn on an agent conversation. Used as-is by the
        non-streaming `POST /agents/{agentKey}/conversations/{conversationId}/messages`,
        where `chatMode` may be omitted; `AgentAddMessageStreamRequest`
        additionally requires it. Unknown fields are stripped during validation.
      required:
      - query
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 100000
          description: |
            User follow-up prompt to append to the existing agent conversation.
            Saved as a new `user_query` message before the upstream AI stream
            starts.
        filters:
          allOf:
          - $ref: '#/components/schemas/Filters'
          description: |
            Optional retrieval scope (`apps` / `kb`) for this turn. Each id must
            be a valid UUID. Omit to let the agent use its stored defaults;
            send `{ "apps": [], "kb": [] }` to force no knowledge sources for this turn.
        appliedFilters:
          allOf:
          - $ref: '#/components/schemas/AppliedFilters'
          description: |
            UI filter state persisted on the saved user message. Not used for
            retrieval and not forwarded to the upstream agent backend.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ChatAttachmentRef'
          description: |
            Uploaded attachments to ground this turn. Each entry references a
            record id returned from the agent attachment upload endpoint.
        chatMode:
          type: string
          enum:
          - quick
          description: |
            Execution mode. Scoped agent conversations support only `quick`.
            Required on the `/stream` route; optional on the non-streaming
            route.
        modelKey:
          type: string
          minLength: 1
          description: |
            AI model configuration id override for this turn. Omit to use the
            agent's default model. A key that names no configured model is not
            refused: the turn runs on the organization's default model.
        modelName:
          type: string
          minLength: 1
          description: Provider model name (the underlying LLM identifier).
        modelFriendlyName:
          type: string
          minLength: 1
          description: Friendly UI label for the selected model.
        timezone:
          type: string
          minLength: 1
          description: |
            Client IANA timezone, such as `America/New_York`. Helps the agent
            resolve relative date references in the prompt.
        currentTime:
          type: string
          format: date-time
          pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$
          description: |
            Client time in ISO 8601 / RFC 3339 format (UTC `Z` or numeric
            offset). Sent alongside `timezone` for time-aware answers.
        tools:
          type: array
          items:
            type: string
            minLength: 1
          description: |
            Allowed tool ids for this turn, such as `jira.create_issue`. Omit
            to let the agent use its default toolset; send `[]` to disable
            tools for this turn. A list that leaves out `web_search` turns off
            the agent's web search for the turn.
        protocol:
          type: string
          enum:
          - agui
          description: |
            AG-UI is the only supported wire protocol. When present must be
            `"agui"`. Omitting the field is equivalent — the server always
            uses the AG-UI vocabulary (see `AgentMessageStreamSSEEvent`).
            Kept in the schema for backward compatibility with callers that
            already send it.
        agentCapabilities:
          $ref: '#/components/schemas/AgentCapabilities'
        includeRetrievalContext:
          type: boolean
          default: false
          description: 'Opt in to measurement frames on this stream: CUSTOM `retrieval_context` events naming the records and blocks that reached the model, and one CUSTOM `run_usage` event carrying the run''s token totals and loop outcome. Identifiers only, never block text. Does not change the answer.'
        keywordSearchBudget:
          type: string
          enum:
          - short
          - full
          description: How long each search waits for the keyword (grep) match after its semantic results are in. `short` waits at most 5 seconds and keeps the keyword matches found by then, for callers that would rather answer sooner, such as agents calling chat over MCP. `full`, or leaving it out, waits for all of it. Deployments running `HIGH_ACCURACY_MODE` always wait in full.
        toolApproval:
          $ref: '#/components/schemas/ToolApprovalAnswer'
        runId:
          type: string
          format: uuid
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
          description: |
            Client-generated identifier for this run. Send it here to enable
            `POST /agents/{agentKey}/conversations/{conversationId}/cancel
            {runId}` while the stream is still generating.
        reasoningEffort:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: |
            Reasoning effort for this turn, for models that support it. Stored on
            the conversation's model info and forwarded to the AI backend.
      example:
        query: can you elaborate on the latest headlines?
        modelKey: 5c1832f4-fa19-4167-b913-307fad3a6551
        modelName: gpt-5.6-luna
        modelFriendlyName: GPT 5.4 mini
        chatMode: quick
        timezone: Asia/Kolkata
        currentTime: '2026-05-19T12:58:01+05:30'
        tools: []
        filters:
          apps:
          - 2605c882-61d4-4aa2-b480-a68c957c151d
          - ed6d6cc4-70bd-4838-9aeb-488e910c833a
          kb:
          - 8747da12-4724-4a95-ac92-827b88d79647
        appliedFilters:
          apps:
          - id: 2605c882-61d4-4aa2-b480-a68c957c151d
            name: US Headlines, abcnews
            nodeType: app
            connector: RSS
          - id: ed6d6cc4-70bd-4838-9aeb-488e910c833a
            name: ABC News RSS
            nodeType: app
            connector: RSS
          kb:
          - id: 8747da12-4724-4a95-ac92-827b88d79647
            name: Siddhant Ota's Private
            nodeType: recordGroup
            connector: KB
    MessageToolCall:
      type: object
      additionalProperties: false
      description: One tool invocation recorded on a message turn.
      properties:
        toolName:
          type: string
        toolResult: {}
    MessageReasoningTurn:
      type: object
      additionalProperties: false
      description: |
        One model turn's chain-of-thought. Persisted only when reasoning
        persistence is enabled; the array is empty otherwise.
      required:
      - content
      properties:
        messageId:
          type: string
        turnIndex:
          type: number
        content:
          type: string
    MessagePart:
      type: object
      additionalProperties: false
      description: |
        One entry in the ordered agent-activity transcript for a message turn.
        Every field beyond `type` is optional and depends on the part kind, and
        `sub_agent` nests this same shape recursively under `parts`.

        Tool results here are always a bounded preview, never the full payload —
        `artifactId` points at the complete result.
      properties:
        type:
          type: string
          enum:
          - text
          - reasoning
          - tool_call
          - sub_agent
        content:
          type: string
        toolCallId:
          type: string
        toolName:
          type: string
        displayName:
          type: string
        args:
          type: string
        argsSummary:
          type: string
          description: Human-readable summary of `args`, computed server-side.
        status:
          type: string
          enum:
          - running
          - completed
          - failed
          - blocked
        resultPreview:
          type: string
        resultSummary:
          type: string
          description: |
            Human-readable summary of the tool result, computed server-side from
            the full untruncated output.
        artifactId:
          type: string
          description: Blob-backed artifact id for the full tool result.
        runId:
          type: string
        roleName:
          type: string
        isFinal:
          type: boolean
          description: |
            Set on the single root-level `text` part carrying the answer. Every
            other root `text` part is an abandoned preamble turn. Never set on
            child parts nested under a `sub_agent`.
        parts:
          type: array
          description: Nested transcript of a `sub_agent` part.
          items:
            $ref: '#/components/schemas/MessagePart'
    Message:
      type: object
      additionalProperties: false
      description: |
        A single message within a conversation. Messages can be user queries,
        AI responses, system messages, or error notifications.
      properties:
        _id:
          type: string
          format: objectId
          description: Unique message identifier
        messageType:
          type: string
          enum:
          - user_query
          - bot_response
          - error
          - feedback
          - system
          - tool_call
          description: |
            Type of message:
            - `user_query` - User's question or input
            - `bot_response` - AI-generated response
            - `error` - Error message from the system
            - `feedback` - User feedback on a response
            - `system` - System notification or status
            - `tool_call` - Tool invocation turn; details are on `tools`
        content:
          type: string
          description: The message text content
        contentFormat:
          type: string
          enum:
          - MARKDOWN
          - JSON
          - HTML
          description: Format of the content for rendering
          default: MARKDOWN
        citations:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/CitationReference'
            - $ref: '#/components/schemas/PopulatedCitationReference'
            - $ref: '#/components/schemas/RedactedSource'
          description: |
            References to source documents used in the response. Routes that
            return the saved conversation after a turn (create, add message)
            populate each item to `{ citationId, citationData }`.
        confidence:
          type: string
          nullable: true
          description: |
            AI confidence in the answer. Present only on `bot_response` messages,
            and only when the model emitted a trailing confidence block.

            This field is now optional and nullable; it was previously always present and non-nullable. Treat a missing or `null` value as "no confidence reported" and guard before using it. Change effective in SDK v1.3.0 (v1.2.0 and earlier always populated it).
        followUpQuestions:
          type: array
          items:
            $ref: '#/components/schemas/FollowUpQuestion'
          description: Suggested follow-up questions
        feedback:
          type: array
          items:
            $ref: '#/components/schemas/MessageFeedback'
          description: User feedback on this message
        metadata:
          type: object
          additionalProperties: false
          properties:
            processingTimeMs:
              type: number
              description: Time taken to generate response in milliseconds
            modelVersion:
              type: string
              description: Version of the AI model used
            aiTransactionId:
              type: string
              description: Transaction ID for tracking in AI backend
            reason:
              type: string
              description: Additional context or reasoning
        modelInfo:
          $ref: '#/components/schemas/ConversationModelInfo'
        appliedFilters:
          $ref: '#/components/schemas/AppliedFilters'
        referenceData:
          type: array
          description: |
            Reference identifiers extracted from tool responses, used to scope
            follow-up queries (for example Jira project keys or record IDs).
          items:
            anyOf:
            - type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: Display name shown to the user.
                id:
                  type: string
                  description: Technical identifier (numeric ID, UUID, etc.).
                type:
                  type: string
                  description: Item type (e.g. `project`, `issue`, `file`, `notebook`, `page`).
                app:
                  type: string
                  description: |
                    Source application (e.g. `jira`, `confluence`, `sharepoint`,
                    `slack`, `drive`, `gmail`).
                webUrl:
                  type: string
                  description: URL to open the item in a browser.
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                  description: |
                    App-specific fields keyed by name (e.g. `key` for a Jira project,
                    `siteId` for a SharePoint document).
            - $ref: '#/components/schemas/RedactedSource'
        attachments:
          type: array
          description: |
            Files uploaded for this message turn (see
            `POST /conversations/attachments/upload`).
          items:
            $ref: '#/components/schemas/ChatAttachmentRef'
        tools:
          type: array
          description: Tool call results invoked during this message turn.
          items:
            $ref: '#/components/schemas/MessageToolCall'
        reasoning:
          type: array
          description: Persisted chain-of-thought for this turn.
          items:
            $ref: '#/components/schemas/MessageReasoningTurn'
        parts:
          type: array
          description: Ordered agent-activity transcript for this turn.
          items:
            $ref: '#/components/schemas/MessagePart'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    RedactedSource:
      type: object
      additionalProperties: false
      description: |
        Stands in for a source the viewer of a shared chat or search cannot read:
        a citation, reference, filter node or search hit with no id, name, link or
        text. Only the owner of a conversation or search sees every source.
      required:
      - redacted
      - reason
      properties:
        redacted:
          type: boolean
          enum:
          - true
        reason:
          type: string
          enum:
          - no_access
        name:
          type: string
          description: A neutral label (`Restricted source`).
    CitationReference:
      type: object
      additionalProperties: false
      description: Reference to a source document cited in a response
      properties:
        citationId:
          type: string
          format: objectId
          description: ID of the citation record
        relevanceScore:
          type: number
          minimum: 0
          maximum: 1
          description: How relevant this citation is to the query (0-1)
        excerpt:
          type: string
          description: Relevant excerpt from the source document
        context:
          type: string
          description: Additional context around the citation
    PopulatedCitationReference:
      type: object
      additionalProperties: false
      description: |
        A message's citation reference after the handler populates it: the
        stored reference fields, with `citationId` as the id and the cited
        document under `citationData`.
      properties:
        citationId:
          type: string
          format: objectId
          description: ID of the citation record
        relevanceScore:
          type: number
          minimum: 0
          maximum: 1
          description: How relevant this citation is to the query (0-1)
        excerpt:
          type: string
          description: Relevant excerpt from the source document
        context:
          type: string
          description: Additional context around the citation
        citationData:
          $ref: '#/components/schemas/Citation'
    Citation:
      type: object
      additionalProperties: false
      description: |
        A populated citation document. Represents a single chunk of source
        content (e.g. a passage from a document or record) referenced by an
        AI response, together with its provenance metadata.
      required:
      - _id
      - content
      - chunkIndex
      - citationType
      - metadata
      - createdAt
      - updatedAt
      properties:
        _id:
          type: string
          format: objectId
        content:
          type: string
          description: The cited text chunk
        chunkIndex:
          type: integer
          description: Index of this chunk within the source record
        citationType:
          type: string
          description: Source type identifier (e.g. `vectordb|document`)
        metadata:
          $ref: '#/components/schemas/PersistedSemanticSearchCitationMetadata'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ConversationModelInfo:
      type: object
      additionalProperties: false
      description: AI model configuration recorded against a conversation or message.
      properties:
        modelKey:
          type: string
          description: Stable identifier of the configured model record
        modelName:
          type: string
          description: Provider-facing model name (e.g. `gpt-5.6-luna`)
        modelProvider:
          type: string
          description: Provider key (e.g. `openai`, `anthropic`)
        modelFriendlyName:
          type: string
          description: Human-readable display name
        chatMode:
          type: string
          description: Chat mode used for this turn (e.g. `quick`, `internal_search`)
        reasoningEffort:
          type: string
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: Reasoning effort requested for the turn, when one was set.
    FollowUpQuestion:
      type: object
      additionalProperties: false
      description: AI-suggested follow-up question
      properties:
        question:
          type: string
          description: The suggested question text
        confidence:
          type: string
          description: Confidence level for this suggestion
        reasoning:
          type: string
          description: Why this question might be relevant
    MessageFeedbackSubmitRequest:
      type: object
      additionalProperties: false
      description: |
        Gateway request body for submitting message feedback (Zod
        `feedbackBodySchema`). All fields are optional; an empty object is
        accepted. Matches the first-party chat UI payload shape.
      properties:
        isHelpful:
          type: boolean
          description: Overall helpfulness signal (thumbs up/down).
        categories:
          type: array
          description: Issue or positive categories that apply to the response.
          items:
            type: string
            enum:
            - incorrect_information
            - missing_information
            - irrelevant_information
            - unclear_explanation
            - poor_citations
            - excellent_answer
            - helpful_citations
            - well_explained
            - other
        comments:
          type: object
          additionalProperties: false
          description: Free-text comments grouped by sentiment.
          properties:
            positive:
              type: string
              description: What was good about the response.
            negative:
              type: string
              description: What could be improved.
    MessageFeedback:
      type: object
      additionalProperties: false
      description: |
        Comprehensive feedback on an AI response. Feedback helps improve
        the AI's performance and response quality over time.
      properties:
        isHelpful:
          type: boolean
          description: Overall helpfulness rating
        ratings:
          type: object
          additionalProperties: false
          properties:
            accuracy:
              type: integer
              minimum: 1
              maximum: 5
              description: How accurate was the information (1-5)
            relevance:
              type: integer
              minimum: 1
              maximum: 5
              description: How relevant was the response (1-5)
            completeness:
              type: integer
              minimum: 1
              maximum: 5
              description: How complete was the answer (1-5)
            clarity:
              type: integer
              minimum: 1
              maximum: 5
              description: How clear was the explanation (1-5)
        categories:
          type: array
          items:
            type: string
            enum:
            - incorrect_information
            - missing_information
            - irrelevant_information
            - unclear_explanation
            - poor_citations
            - excellent_answer
            - helpful_citations
            - well_explained
            - other
          description: Categories of issues or positive attributes identified
        comments:
          type: object
          additionalProperties: false
          properties:
            positive:
              type: string
              description: What was good about the response
            negative:
              type: string
              description: What could be improved
            suggestions:
              type: string
              description: Specific suggestions for improvement
        citationFeedback:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              _id:
                type: string
                format: objectId
                description: Auto-generated sub-document identifier
              citationId:
                type: string
                format: objectId
              isRelevant:
                type: boolean
              relevanceScore:
                type: integer
                minimum: 1
                maximum: 5
              comment:
                type: string
          description: Feedback on individual citations
        followUpQuestionsHelpful:
          type: boolean
          description: Were the suggested follow-up questions helpful
        unusedFollowUpQuestions:
          type: array
          items:
            type: string
          description: Follow-up questions that were suggested but not used by the user
        source:
          type: string
          enum:
          - user
          - system
          - admin
          - auto
          default: user
          description: Origin of the feedback. Always present in responses (server applies the default `user`).
        feedbackProvider:
          type: string
          format: objectId
          description: User who submitted the feedback
        timestamp:
          type: integer
          format: int64
          description: |
            Time the feedback was created, stored as a Number (epoch milliseconds)
            with a server-side default of `Date.now`, so always present in responses.
            Not an ISO 8601 datetime.
        revisions:
          type: array
          description: Audit trail of edits to this feedback entry
          items:
            type: object
            additionalProperties: false
            properties:
              _id:
                type: string
                format: objectId
                description: Auto-generated sub-document identifier
              updatedFields:
                type: array
                items:
                  type: string
                description: Names of feedback fields modified in this revision
              previousValues:
                type: object
                additionalProperties: true
                description: |
                  Map of previously-set values for the fields named in `updatedFields`,
                  keyed by field name. Stored as a Mongoose Map of Mixed values.
              updatedBy:
                type: string
                format: objectId
              updatedAt:
                type: integer
                format: int64
                description: Time the revision was recorded, as epoch milliseconds.
        metrics:
          type: object
          additionalProperties: false
          description: Optional telemetry captured alongside the feedback
          properties:
            timeToFeedback:
              type: number
              description: Time from response delivery to feedback submission
            userInteractionTime:
              type: number
              description: Total time the user spent reviewing the response
            feedbackSessionId:
              type: string
            userAgent:
              type: string
            platform:
              type: string
    MessageFeedbackAppendMetrics:
      type: object
      additionalProperties: false
      required:
      - timeToFeedback
      description: |
        Telemetry recorded server-side alongside the feedback. Always present
        on append responses.
      properties:
        timeToFeedback:
          type: number
          description: |
            Milliseconds between message creation and feedback submission.
            Always present.
        userAgent:
          type: string
          description: Value of the `User-Agent` request header captured server-side.
    MessageFeedbackAppendEntry:
      type: object
      additionalProperties: false
      required:
      - feedbackProvider
      - timestamp
      - metrics
      description: |
        The feedback entry just appended to the message. Echoes the fields
        supplied in the request plus server-stamped `feedbackProvider`,
        `timestamp`, and `metrics`.
      properties:
        isHelpful:
          type: boolean
          description: Echoed from the request when supplied.
        categories:
          type: array
          description: Echoed categories from the request.
          items:
            type: string
            enum:
            - incorrect_information
            - missing_information
            - irrelevant_information
            - unclear_explanation
            - poor_citations
            - excellent_answer
            - helpful_citations
            - well_explained
            - other
        comments:
          type: object
          additionalProperties: false
          description: Echoed free-text comments from the request.
          properties:
            positive:
              type: string
            negative:
              type: string
        feedbackProvider:
          type: string
          format: objectId
          description: User who submitted the feedback. Always present.
        timestamp:
          type: integer
          format: int64
          description: |
            Submission time as epoch milliseconds (not an ISO 8601 datetime).
            Always present.
        metrics:
          $ref: '#/components/schemas/MessageFeedbackAppendMetrics'
    MessageFeedbackUpdateResponse:
      type: object
      additionalProperties: false
      required:
      - conversationId
      - messageId
      - feedback
      - meta
      description: |
        Gateway response after appending feedback to a bot-response message.
      properties:
        conversationId:
          type: string
          format: objectId
          description: Conversation the feedback was attached to.
        messageId:
          type: string
          format: objectId
          description: Message the feedback was attached to.
        feedback:
          $ref: '#/components/schemas/MessageFeedbackAppendEntry'
        meta:
          type: object
          additionalProperties: false
          required:
          - requestId
          - timestamp
          - duration
          properties:
            requestId:
              type: string
              description: |
                Server-side request identifier. Read from the `X-Request-ID`
                header when supplied, otherwise auto-generated, so this field
                is always present.
            timestamp:
              type: string
              format: date-time
            duration:
              type: integer
              description: Server-side processing time in milliseconds.
    Conversation:
      type: object
      description: |
        A conversation represents a chat session between a user and the AI.
        Conversations maintain context across multiple messages and can be
        shared, archived, and organized.
      properties:
        _id:
          type: string
          format: objectId
          description: Unique conversation identifier
        userId:
          type: string
          format: objectId
          description: ID of the user who owns this conversation
        orgId:
          type: string
          format: objectId
          description: Organization this conversation belongs to
        title:
          type: string
          description: |
            Conversation title, auto-generated from first query
            or manually updated
          example: Q4 Financial Report Discussion
        initiator:
          type: string
          format: objectId
          description: User who started the conversation
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
          description: All messages in this conversation
        status:
          type: string
          enum:
          - None
          - Inprogress
          - Complete
          - Failed
          - Stopped
          description: |
            Current status of the conversation:
            - `None` — no activity yet
            - `Inprogress` — AI is processing
            - `Complete` — response ready
            - `Failed` — error occurred
            - `Stopped` — cancelled, or the client disconnected mid-answer;
              the last message keeps the partial answer
        failReason:
          type: string
          description: Error description, populated only when `status` is `Failed`.
        modelInfo:
          type: object
          properties:
            modelKey:
              type: string
            modelName:
              type: string
            modelFriendlyName:
              type: string
              description: Friendly display name of the selected model
            modelProvider:
              type: string
            chatMode:
              type: string
            reasoningEffort:
              type: string
              enum:
              - none
              - low
              - medium
              - high
              - max
              description: Reasoning effort requested for the turn, when one was set.
          description: AI model configuration used
        isShared:
          type: boolean
          default: false
          description: Whether this conversation is shared with others
        shareLink:
          type: string
          description: Shareable link if conversation is shared
        sharedWith:
          type: array
          items:
            type: object
            properties:
              userId:
                type: string
                format: objectId
              accessLevel:
                type: string
                enum:
                - read
                - write
              _id:
                type: string
                format: objectId
                description: Subdocument identifier auto-assigned by MongoDB.
          description: Users this conversation is shared with
        isArchived:
          type: boolean
          default: false
          description: Whether this conversation is archived
        archivedBy:
          type: string
          format: objectId
          nullable: true
          description: |
            User ID of the last user who archived this row, or `null` after
            unarchive cleared the archive state. Absent on rows that have
            never been archived.
        isDeleted:
          type: boolean
          default: false
          description: Whether this conversation has been soft-deleted.
        deletedBy:
          type: string
          format: objectId
          description: User who soft-deleted this conversation.
        conversationErrors:
          type: array
          description: Errors recorded against this conversation (e.g. failed message generations).
          items:
            type: object
            required:
            - message
            properties:
              _id:
                type: string
                format: objectId
                description: Sub-document identifier auto-assigned by MongoDB.
              message:
                type: string
              errorType:
                type: string
              timestamp:
                type: string
                format: date-time
              messageId:
                type: string
                format: objectId
              stack:
                type: string
              metadata:
                type: object
                additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
          description: Free-form metadata attached to the conversation.
        lastActivityAt:
          type: integer
          description: Unix timestamp of last activity
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        isOwner:
          type: boolean
          description: |
            Computed per request. `true` when the requesting user is the
            conversation's `initiator`.
          readOnly: true
        accessLevel:
          type: string
          enum:
          - read
          - write
          description: |
            Computed per request. The requester's effective access level:
            their entry in `sharedWith`, or `read` by default.
          readOnly: true
        projectId:
          type: string
          format: objectId
          nullable: true
          description: |
            The project this conversation is linked to, if any. Set via
            `PUT /conversations/{conversationId}/project` or at creation
            time; absent on conversations that were never linked.
        projectVisibility:
          type: string
          enum:
          - private
          - project
          nullable: true
          description: |
            Only meaningful when `projectId` is set. `private` (default)
            keeps the conversation visible to its owner only; `project`
            exposes it to every member of the linked project. See
            `PATCH /conversations/{conversationId}/project-visibility`.
        sharedBy:
          $ref: '#/components/schemas/ConversationSharedBy'
        agentKey:
          type: string
          description: |
            Only on agent conversations (returned by `GET /conversations?source=shared`). Open
            them with `GET /agents/{agentKey}/conversations/{conversationId}`.
        __v:
          type: integer
          readOnly: true
          description: Mongoose document version key.
    ConversationSharedBy:
      type: object
      additionalProperties: false
      description: |
        Present on conversations the caller received via share. Identifies the
        conversation initiator (the only user who can share a chat).
      required:
      - userId
      - name
      properties:
        userId:
          type: string
          format: objectId
        name:
          type: string
          description: Display name, falling back to email or the user id
    ConversationListItem:
      type: object
      description: |
        Conversation summary returned by list endpoints. Identical to
        `Conversation` but omits `messages` to keep list payloads small.
        Fetch a single conversation to retrieve its messages.
      properties:
        agentKey:
          type: string
          description: |
            Only on agent conversations (returned by `GET /conversations?source=shared`). Open
            them with `GET /agents/{agentKey}/conversations/{conversationId}`.
        _id:
          type: string
          format: objectId
        userId:
          type: string
          format: objectId
        orgId:
          type: string
          format: objectId
        title:
          type: string
        initiator:
          type: string
          format: objectId
        status:
          type: string
          enum:
          - None
          - Inprogress
          - Complete
          - Failed
          - Stopped
        failReason:
          type: string
        modelInfo:
          type: object
          properties:
            modelKey:
              type: string
            modelName:
              type: string
            modelFriendlyName:
              type: string
            modelProvider:
              type: string
            chatMode:
              type: string
            reasoningEffort:
              type: string
              enum:
              - none
              - low
              - medium
              - high
              - max
              description: Reasoning effort requested when the conversation was created, when one was set.
        isShared:
          type: boolean
        shareLink:
          type: string
        sharedWith:
          type: array
          items:
            type: object
            properties:
              userId:
                type: string
                format: objectId
              accessLevel:
                type: string
                enum:
                - read
                - write
              _id:
                type: string
                format: objectId
                description: Subdocument identifier auto-assigned by MongoDB.
        isArchived:
          type: boolean
        archivedBy:
          type: string
          format: objectId
          nullable: true
          description: |
            User ID of the last user who archived this row, or `null` after
            unarchive cleared the archive state. Absent on rows that have
            never been archived.
        isDeleted:
          type: boolean
        deletedBy:
          type: string
          format: objectId
        conversationErrors:
          type: array
          items:
            type: object
            properties:
              _id:
                type: string
                format: objectId
                description: Sub-document identifier auto-assigned by MongoDB.
              message:
                type: string
              errorType:
                type: string
              timestamp:
                type: string
                format: date-time
              messageId:
                type: string
                format: objectId
              stack:
                type: string
              metadata:
                type: object
                additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        lastActivityAt:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        isOwner:
          type: boolean
          readOnly: true
        accessLevel:
          type: string
          enum:
          - read
          - write
          readOnly: true
        isPinned:
          type: boolean
          description: |
            `true` when the owner pinned this conversation. Absent on
            conversations that are not pinned (never `false`). Set via
            `PATCH /conversations/{conversationId}/pin`. Only returned to the
            owner: lists with `source=shared` omit it.
        projectId:
          type: string
          format: objectId
          nullable: true
          description: |
            The project this conversation is linked to, if any. Set via
            `PUT /conversations/{conversationId}/project` or at creation
            time; absent on conversations that were never linked.
        projectVisibility:
          type: string
          enum:
          - private
          - project
          nullable: true
          description: |
            Only meaningful when `projectId` is set. `private` (default)
            keeps the conversation visible to its owner only; `project`
            exposes it to every member of the linked project. See
            `PATCH /conversations/{conversationId}/project-visibility`.
        sharedBy:
          $ref: '#/components/schemas/ConversationSharedBy'
    ConversationPinResponse:
      type: object
      additionalProperties: false
      required:
      - id
      - isPinned
      - meta
      properties:
        id:
          type: string
          format: objectId
          description: Conversation identifier
        isPinned:
          type: boolean
          description: The conversation's pin state after the call.
        meta:
          type: object
          additionalProperties: false
          properties:
            requestId:
              type: string
              description: Request correlation identifier
            timestamp:
              type: string
              format: date-time
              description: Response generation timestamp
            duration:
              type: integer
              description: Server processing time in milliseconds
    ForkConversationResponse:
      type: object
      additionalProperties: false
      required:
      - id
      - title
      - forkedFrom
      - messageCount
      - meta
      properties:
        id:
          type: string
          format: objectId
          description: New conversation identifier
        title:
          type: string
          description: Title of the forked conversation
        projectId:
          type: string
          format: objectId
          description: |
            Project the fork is linked to. Present only when the source conversation
            belonged to a project that the caller can still view; otherwise omitted.
        forkedFrom:
          type: object
          additionalProperties: false
          required:
          - conversationId
          - messageId
          properties:
            conversationId:
              type: string
              format: objectId
            messageId:
              type: string
              format: objectId
        messageCount:
          type: integer
          minimum: 0
          description: Number of messages copied into the new conversation
        meta:
          type: object
          additionalProperties: false
          required:
          - timestamp
          - duration
          properties:
            requestId:
              type: string
            timestamp:
              type: string
              format: date-time
            duration:
              type: integer
              description: Server-side processing time in milliseconds
    RetrieveRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
          minLength: 1
          maxLength: 100000
          description: What to find. This text is always searched.
        limit:
          type: integer
          minimum: 1
          maximum: 50
          default: 8
          description: Most chunks to return, best first. Left out, the AI service uses 8.
        filters:
          $ref: '#/components/schemas/Filters'
        createdAfter:
          type: string
          description: '"YYYY-MM-DD" or an ISO 8601 datetime with an offset, inclusive. When the source record was created.'
          minLength: 1
          maxLength: 64
        createdBefore:
          type: string
          description: As `createdAfter`, the other end.
          minLength: 1
          maxLength: 64
        modifiedAfter:
          type: string
          description: As `createdAfter`, on when the source record last changed.
          minLength: 1
          maxLength: 64
        modifiedBefore:
          type: string
          description: As `modifiedAfter`, the other end.
          minLength: 1
          maxLength: 64
        maxChunksPerRecord:
          type: integer
          minimum: 1
          maximum: 50
          description: |
            Most chunks from any one record. Left out, the search's own per-record
            allowance applies: at most `max(4, limit / 6)` passages from one record
            with default settings (4 at `limit` 8, 8 at `limit` 50). With `limit`
            4 or less, one record can fill the page.
        rewriteQuery:
          type: boolean
          default: false
          description: |
            Also search rewritten and expanded versions of the query, made by the
            org's model (slower). The original text is still searched.
    RetrieveChunk:
      type: object
      required:
      - id
      - text
      - record
      - citation
      properties:
        id:
          type: string
          description: Stable for the same indexed block, for deduplication and caching.
        text:
          type: string
        score:
          type: number
          nullable: true
        record:
          type: object
          properties:
            recordId:
              type: string
            name:
              type: string
              nullable: true
            connector:
              type: string
              nullable: true
            mimeType:
              type: string
              nullable: true
            updatedAt:
              type: string
              nullable: true
          additionalProperties: false
          required:
          - recordId
          - name
          - connector
          - mimeType
          - updatedAt
        citation:
          type: object
          properties:
            url:
              type: string
              nullable: true
              description: Deep link to the passage (a `#:~:text=` fragment where the source supports one).
            recordUrl:
              type: string
              nullable: true
              description: Link to the record itself.
            pageNum:
              type: array
              nullable: true
              items:
                type: integer
            blockIndex:
              type: integer
              nullable: true
          additionalProperties: false
          required:
          - url
          - recordUrl
          - pageNum
          - blockIndex
      additionalProperties: false
    RetrieveResponse:
      type: object
      required:
      - chunks
      - incomplete
      properties:
        requestId:
          type: string
          description: The request's id, as in the `x-request-id` response header.
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/RetrieveChunk'
        incomplete:
          type: boolean
          description: True when part of the search could not run (for example a source timed out).
        message:
          type: string
          description: Why `chunks` is empty, when it is; `null` when the search gave no reason. Absent when `chunks` is not empty.
          nullable: true
      additionalProperties: false
    SemanticSearchRequest:
      type: object
      description: |
        Request body for performing semantic search across the enterprise knowledge base.

        **How Semantic Search Works:**

        1. Query is converted to vector embeddings
        2. Similar content is found using vector similarity
        3. Results are ranked by relevance score
        4. Matching chunks with metadata are returned

        **Filtering:**

        Use filters to narrow search scope to specific apps or knowledge bases.

        **Date bounds** (`createdAfter`, `createdBefore`, `modifiedAfter`, `modifiedBefore`)
        match when a record was written or last changed, not when an event it describes
        happened. With any of them set, and while the server's `DATE_FILTER_SAFETY_NET` setting
        is on (the default), the same search also runs once without dates, and its best matches
        that the bounds left out come back apart from the results, in
        `searchResponse.outsideDates`. With the setting off, no such search runs and
        `outsideDates` is omitted.
      required:
      - query
      properties:
        query:
          type: string
          minLength: 1
          description: |
            Natural language search query. The system understands
            semantic meaning, not just keywords. A query containing HTML
            markup or a printf-style format specifier (`%s`, `%x`, `%n`) is
            refused with `400` `HTTP_BAD_REQUEST`.
          example: employee onboarding procedures
        filters:
          $ref: '#/components/schemas/Filters'
        limit:
          type: integer
          minimum: 1
          maximum: 100
          description: |
            For a ranked search, the maximum number of passages (entries of `searchResults`) the
            response holds, counted after query expansion and section expansion, so it holds at
            any number of queries. `records` lists only the records those passages come from. A
            search run as a timeline is not cut to `limit` as a whole: `limit` is what each
            period's own search asks for, and a period can hold more (see `timeline`). When the
            timeline was chosen automatically (`timeline` left out), each period asks for at most
            10, whatever `limit` is.

            Left out, it is `10`. A numeric string (`"2"`) is accepted and read as a number; a
            fractional number is refused with `400 VALIDATION_ERROR`.
          default: 10
        createdAfter:
          type: string
          maxLength: 64
          description: |
            Only records the source created on or after this date. `YYYY-MM-DD` (the whole
            day, UTC) or an ISO 8601 datetime with a timezone offset. A date that is not
            one of these, or in the future, is a `400` that says why.
          example: '2026-01-01'
        createdBefore:
          type: string
          maxLength: 64
          description: |
            Only records the source created on or before this date. A `YYYY-MM-DD` value
            includes that whole day.
          example: '2026-03-31'
        modifiedAfter:
          type: string
          maxLength: 64
          description: |
            Only records last changed in the source on or after this date. Same format as
            `createdAfter`.
          example: '2026-09-01'
        modifiedBefore:
          type: string
          maxLength: 64
          description: |
            Only records last changed in the source on or before this date. Same format as
            `createdBefore`. Records with no source date are left out whenever a bound on
            that date is set.
          example: '2026-09-30T23:59:59Z'
        rewriteQuery:
          type: boolean
          default: true
          description: |
            Whether the AI model's rewrite of the query and its expanded variants are
            searched as well. The query as sent is always searched, so an exact code or
            name in it is never lost to the rewrite. Set it to `false` to search the query
            exactly as sent and nothing else, with no
            model call: faster, and suited to callers that write their own queries, such
            as an agent. The results can differ from a search with the rewrite.
          example: false
        timeline:
          type: string
          enum:
          - created
          - modified
          - 'off'
          description: |
            Search a span of time period by period instead of ranking matches over the whole
            span, for questions such as "how did this evolve" or "what changed between March
            and May". A plain search returns the best matches overall, which bunch around one
            moment; a timeline splits the span into up to 6 periods (calendar months, or weeks
            within one month), searches each period on its own and beside one search of the
            whole span, and returns the matches in date order, each labelled with its period.

            The value is the date records are placed by: `created` (when the record was
            created at its source) or `modified` (its last change). The span is that date's
            bounds (`createdAfter` / `createdBefore`, or `modifiedAfter` / `modifiedBefore`);
            with no start it covers the year before the end, or further back to the earliest
            of the best matches. Bounds on the other date apply to every period. `limit` is the
            number of matches each period's own search asks for; matches from
            the search of the whole span (up to 50) are added to the periods their records are
            dated in, so a period can hold more than `limit`. Each search applies the same permissions
            and filters as a plain search.

            Left out, a search whose bounds on one date have a start and cover more than 31
            days (a missing end is today) runs as a timeline on that date, and
            `timeline.automatic` is `true`; any other search is a plain ranked search. `off`
            is always a plain ranked search. A server whose `TIMELINE_SUMMARIES` setting is
            `false` ignores the field and never runs a timeline.
          example: created
        saveHistory:
          type: boolean
          default: true
          description: |
            Whether the search is saved to the caller's search history (`GET /search`)
            with a citation for each match. Set it to `false` for searches that are not
            the user's own, such as an agent searching on their behalf: nothing is
            stored and the response has no `searchId`. A server older than this field
            ignores it and saves the search.
          example: true
    SemanticSearchBoundingBox:
      type: object
      additionalProperties: false
      description: Normalized bounding region for a chunk (when available).
      properties:
        x:
          type: number
        y:
          type: number
    SemanticSearchHitMetadata:
      type: object
      additionalProperties: false
      description: |
        Per-hit metadata after retrieval enrichment (record + vector context).
        Listed fields are the documented contract; Qdrant or pipeline updates may add more keys over time—extend this schema when new stable fields appear.
      properties:
        orgId:
          type: string
          nullable: true
        recordId:
          type: string
          nullable: true
        virtualRecordId:
          type: string
          nullable: true
        recordName:
          type: string
          nullable: true
        recordType:
          type: string
          nullable: true
        recordVersion:
          nullable: true
          oneOf:
          - type: string
          - type: number
        origin:
          type: string
          nullable: true
        connector:
          type: string
          nullable: true
        connectorId:
          type: string
          nullable: true
        connectorInstanceName:
          type: string
          nullable: true
          description: The name the admin gave the connector instance; `connector` is only its type.
        connectorName:
          type: string
          nullable: true
        blockText:
          type: string
          nullable: true
        blockType:
          type: string
          nullable: true
          description: |
            Block type for this hit. Common values: `text`, `image`, `table_row`, `table`,
            `record_summary` (whole-record semantic summary chunk — no block index).
        bounding_box:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/SemanticSearchBoundingBox'
        pageNum:
          type: array
          nullable: true
          items:
            nullable: true
            type: integer
        extension:
          type: string
          nullable: true
        mimeType:
          type: string
          nullable: true
        blockNum:
          type: array
          nullable: true
          items:
            type: number
        chunkIndex:
          type: integer
          nullable: true
        sheetName:
          type: string
          nullable: true
        sheetNum:
          type: integer
          nullable: true
        webUrl:
          type: string
          nullable: true
        previewRenderable:
          type: boolean
          nullable: true
        hideWeburl:
          type: boolean
          nullable: true
        updatedAt:
          type: string
          format: date-time
          nullable: true
        categories:
          type: array
          nullable: true
          items:
            type: string
        departments:
          type: array
          nullable: true
          items:
            type: string
        topics:
          type: array
          nullable: true
          items:
            type: string
        languages:
          type: array
          nullable: true
          items:
            type: string
        subcategoryLevel1:
          type: string
          nullable: true
        subcategoryLevel2:
          type: string
          nullable: true
        subcategoryLevel3:
          type: string
          nullable: true
        score:
          type: number
          nullable: true
        _id:
          type: string
          nullable: true
        _collection_name:
          type: string
          nullable: true
        blockIndex:
          type: integer
          nullable: true
        blockId:
          type: string
          nullable: true
        isBlock:
          type: boolean
          nullable: true
        isBlockGroup:
          type: boolean
          nullable: true
        isRecordSummary:
          type: boolean
          nullable: true
          description: |
            Set to `true` by the indexing pipeline when this vector chunk represents a
            whole-record semantic summary rather than an individual block. When true,
            `blockIndex` is absent and `block_type` on the parent hit is `record_summary`.
        kbId:
          type: string
          nullable: true
          description: Knowledge base id merged from graph record during retrieval (when present).
        point_id:
          description: Qdrant point identifier attached during vector lookup (shape varies by deployment).
          nullable: true
          oneOf:
          - type: string
          - type: integer
          - type: number
    SemanticSearchHit:
      type: object
      additionalProperties: false
      description: |
        One search hit returned by the retrieval service. Most hits use string `content`;
        table or grouped blocks may serialize structured payloads as JSON arrays.
        Listed fields are the documented contract; extend this schema when new stable top-level keys are introduced.
      properties:
        score:
          type: number
          nullable: true
        citationType:
          type: string
          nullable: true
        chunkIndex:
          type: integer
          nullable: true
        metadata:
          $ref: '#/components/schemas/SemanticSearchHitMetadata'
        content:
          type: string
          nullable: true
        virtual_record_id:
          type: string
          nullable: true
        block_type:
          type: string
          nullable: true
          description: |
            Block type for this hit. Common values: `text`, `image`, `table_row`, `table`,
            `record_summary` (whole-record semantic summary — `block_index` is `null` for these hits).
        block_index:
          type: integer
          nullable: true
        qualified_name:
          type: string
          description: |
            For a block of source code, the symbol it holds, written `kind:Scope.name` (for example
            `method:Outer.Inner.run`). A span with no name is addressed by its lines instead:
            `kind:L{line}` for one line (`statements:L1`), `kind:L{start}-{end}` for several
            (`imports:L1-5`), or `kind:anonymous` when it has no line numbers. An empty string for a
            block that is not code.
            Present on a hit that is a code block, and on each passage of a list, thread, text
            section or code group brought back whole because of a match inside it. Absent on any
            other hit that matched directly, on the rows of a table brought back whole, and on
            every piece of a section split around an image: its text, the image, and the text that
            stands in for the image when it is not sent as an image.
        distanceFromMatch:
          type: integer
          minimum: 0
          description: |
            Set on a passage returned because a match inside its section (a thread, a list,
            a table) brought the whole section back: how many blocks it sits from the passage
            the search matched nearest to it. `0` is a matched passage. Absent when the hit matched
            directly or the section matched as a whole.
        block_group_index:
          type: integer
          nullable: true
          description: |
            Set on each passage of a section brought back whole (see `distanceFromMatch`): the
            index of that section in its record, so passages of two sections of one record can be
            told apart. Absent on a hit that matched directly.
        timelinePeriod:
          type: integer
          minimum: 0
          description: |
            Set only on a search with `timeline`: the index in `timeline.periods` of the period
            this hit's record is dated in.
    GraphRecordFields:
      type: object
      description: |
        The fields of a record graph document that every graph backend returns. `id` is not
        among them: a schema that names the record adds it.
      properties:
        recordName:
          type: string
          nullable: true
        externalRecordId:
          type: string
          nullable: true
        recordType:
          type: string
          nullable: true
        origin:
          type: string
          nullable: true
        createdAtTimestamp:
          type: number
          nullable: true
        connectorId:
          type: string
          nullable: true
        orgId:
          type: string
          nullable: true
        updatedAtTimestamp:
          type: number
          nullable: true
        externalGroupId:
          type: string
          nullable: true
        externalParentId:
          type: string
          nullable: true
        externalRevisionId:
          type: string
          nullable: true
        externalRootGroupId:
          type: string
          nullable: true
        recordGroupId:
          type: string
          nullable: true
        version:
          type: number
          nullable: true
        connectorName:
          type: string
          nullable: true
        mimeType:
          type: string
          nullable: true
        webUrl:
          type: string
          nullable: true
        lastSyncTimestamp:
          type: number
          nullable: true
        sourceCreatedAtTimestamp:
          type: number
          nullable: true
        sourceLastModifiedTimestamp:
          type: number
          nullable: true
        isDeleted:
          type: boolean
          nullable: true
        isArchived:
          type: boolean
          nullable: true
        isVLMOcrProcessed:
          type: boolean
          nullable: true
        deletedByUserId:
          type: string
          nullable: true
        restoredAtTimestamp:
          type: number
          nullable: true
          description: When a restore last brought the file back from the trash (epoch milliseconds); see `restoredAtTimestamp` on GET /knowledgeBase/record/{recordId}.
        processingStartedAt:
          type: number
          nullable: true
        queuedAtTimestamp:
          type: number
          nullable: true
        retryNotBefore:
          type: number
          nullable: true
          description: |
            Earliest time (epoch milliseconds) indexing reads a record its source
            rate-limited; see `retryNotBefore` on GET /knowledgeBase/record/{recordId}.
        parsingStatus:
          type: string
          nullable: true
        indexingStatus:
          type: string
          nullable: true
        extractionStatus:
          type: string
          nullable: true
        isLatestVersion:
          type: boolean
          nullable: true
        isDirty:
          type: boolean
          nullable: true
        reason:
          type: string
          nullable: true
        lastIndexTimestamp:
          type: number
          nullable: true
        lastExtractionTimestamp:
          type: number
          nullable: true
        entityExtractionStatus:
          type: string
          nullable: true
          description: |
            Where named-entity extraction stands for the record; see
            `entityExtractionStatus` on GET /knowledgeBase/record/{recordId}.
        lastEntityExtractionTimestamp:
          type: number
          nullable: true
        entityExtractionStrategy:
          type: string
          nullable: true
        entityExtractorVersion:
          type: string
          nullable: true
        summaryDocumentId:
          type: string
          nullable: true
        storageDocumentId:
          type: string
          nullable: true
        virtualRecordId:
          type: string
          nullable: true
        contentRev:
          type: string
          nullable: true
          description: |
            Revision of the record's content (16 lowercase hex characters); see
            `contentRev` on GET /knowledgeBase/record/{recordId}. Absent on
            records not indexed since pipeline stages were introduced.
        previewRenderable:
          type: boolean
          nullable: true
        isShared:
          type: boolean
          nullable: true
        isDependentNode:
          type: boolean
          nullable: true
        parentNodeId:
          type: string
          nullable: true
        hideWeburl:
          type: boolean
          nullable: true
        isInternal:
          type: boolean
          nullable: true
        md5Checksum:
          type: string
          nullable: true
        sizeInBytes:
          type: number
          nullable: true
        definition:
          type: string
          nullable: true
        sourceTables:
          type: array
          nullable: true
          items:
            type: string
        rowCount:
          type: number
          nullable: true
        isPlaceholder:
          type: boolean
          description: |
            `true` when the record is a stub parent created for an ancestor that
            is not yet synced or is out of scope; replaced when the real record syncs.
        location:
          type: string
          description: |
            Where the record sits, from its source down to its parent, as
            `Name (App ID: id) -> Name (Record Group ID: id) -> Name (Record ID: id)`,
            resolved at retrieval time (not stored on the record).
            It names only the ancestors the caller can open; for a connected app
            with a limit, only those inside the limit. Absent when none is left.
        statusSummary:
          type: string
          description: |
            Where a ticket, pull request or project stands, in one short phrase, on
            `records` entries only: for example `Merged 2026-09-25 by alice`,
            `Closed without merging 2026-09-26`, or
            `DONE (Jira: Done), resolved 2026-06-06, assignee Bo, priority HIGH`.
            Dates are days in UTC. Absent for record types with no state of their own.
        linkedRecords:
          type: array
          description: |
            On `records` entries only: the records that name this one (`mentionedIn`) and
            that it names (`linksTo`) by web address or issue key, across connectors,
            limited to records the caller may read, at most 10 per relation. For a
            connected app with a limit, only records inside it. Absent when there are none.
          items:
            $ref: '#/components/schemas/SemanticSearchLinkedRecord'
    SemanticSearchGraphRecord:
      type: object
      description: |
        Graph record vertex returned in `records` and as values of `virtual_to_record_map`.
        All listed fields are optional in the schema so partial or evolving documents validate; typical Arango documents
        usually include `_key`, `_id`, `_rev`, `orgId`, `recordName`, `externalRecordId`, `recordType`, `origin`,
        `createdAtTimestamp`, and `connectorId`. Extend this schema when new stable fields appear on Record vertices.

        For a connected app with a limit, a parent the limit leaves out is not named: `recordGroupId`
        (with `externalGroupId`), `rootRecordGroupId` and `parentNodeId` (with `externalParentId`) are `null`
        for it, and `location` keeps only the part of the trail inside the limit, or is left out.
        `connectorInstanceName`, the source's or collection's own name, is left out unless the limit
        covers that app whole; this applies to each hit's `metadata` too.
      allOf:
      - $ref: '#/components/schemas/GraphRecordFields'
      - type: object
        properties:
          _key:
            type: string
            nullable: true
          _id:
            type: string
            nullable: true
          _rev:
            type: string
            nullable: true
    SemanticSearchLinkedRecord:
      type: object
      additionalProperties: false
      required:
      - relation
      - recordId
      - recordName
      - recordType
      - connector
      properties:
        relation:
          type: string
          enum:
          - mentionedIn
          - linksTo
        recordId:
          type: string
        recordName:
          type: string
        recordType:
          type: string
        connector:
          type: string
        status:
          type: string
          description: The linked record's `statusSummary`, when it has one.
    SemanticSearchAppliedFilters:
      type: object
      additionalProperties: false
      description: Present when KB filters were applied to the search request.
      required:
      - kb
      - kb_count
      properties:
        kb:
          type: array
          items:
            type: string
        kb_count:
          type: integer
    SemanticSearchAiResponse:
      type: object
      additionalProperties: false
      description: |
        Payload returned by the AI retrieval service for a semantic search (embedded in `searchResponse`).
        Optional `virtual_to_record_map` maps each virtual record id (string key) to one resolved graph record document.
        Empty responses from the retrieval layer omit `virtual_to_record_map`; success payloads may include it alongside hits and records.
      required:
      - searchResults
      - records
      - status
      - status_code
      - message
      properties:
        searchResults:
          type: array
          items:
            $ref: '#/components/schemas/SemanticSearchHit'
        records:
          type: array
          items:
            $ref: '#/components/schemas/SemanticSearchGraphRecord'
        status:
          type: string
        status_code:
          type: integer
        message:
          type: string
        appliedFilters:
          $ref: '#/components/schemas/SemanticSearchAppliedFilters'
        omittedPassages:
          type: object
          description: |
            Present only when some records lost passages to the per-record cap: maps a
            `recordId` to how many of its passages were left out. Each record keeps at most
            `max(SEARCH_PER_RECORD_FLOOR, limit / SEARCH_PER_RECORD_DIVISOR)` passages
            (4 at the default limit): the passages that matched first, then those nearest a match.
          additionalProperties:
            type: integer
            minimum: 1
        virtual_to_record_map:
          type: object
          description: Maps virtual record id (object property name) to the accessible graph record document for that id.
          additionalProperties:
            $ref: '#/components/schemas/SemanticSearchGraphRecord'
        timeline:
          $ref: '#/components/schemas/SemanticSearchTimeline'
        outsideDates:
          $ref: '#/components/schemas/SemanticSearchOutsideDates'
        searchIncomplete:
          type: string
          description: |
            Present only when part of the search index could not be searched, so the
            results may miss documents: says how many parts failed, for example
            `1 of 3 parts of the search index could not be searched, so this search may
            have missed documents.`
    SemanticSearchOutsideDates:
      type: object
      additionalProperties: false
      description: |
        Present only on a search with date bounds, when the same search without them found
        matches the bounds left out. Date bounds match when a record was written or last changed,
        not when the event it describes happened, so release notes, a retrospective or a weekly
        summary written after a period are left out of a search bounded to that period. The
        search without dates, with the same query, filters and permissions and a limit of 10,
        runs beside the bounded search (or beside a timeline's searches: one plain search, not a
        second timeline). Its best matches outside the bounds, up to 3 records, best first, come
        here, never in `searchResults`, which are unchanged. When nothing inside the bounds
        matched, the response is then a `200` with empty `searchResults`. A server whose
        `DATE_FILTER_SAFETY_NET` setting is `false` never sends this field.
      required:
      - note
      - searchResults
      - records
      properties:
        note:
          type: string
          description: A plain-language label for these matches, to pass on with them.
        searchResults:
          type: array
          description: Up to 3 passages of each record, best first.
          items:
            $ref: '#/components/schemas/SemanticSearchHit'
        records:
          type: array
          description: The records, best first, with their source dates.
          items:
            $ref: '#/components/schemas/SemanticSearchGraphRecord'
    SemanticSearchTimeline:
      type: object
      additionalProperties: false
      description: |
        Present only on a search run as a timeline: one with `timeline` set, or one over a span
        of more than 31 days with it left out. `searchResults` then come period by period,
        oldest first, and by record date within a period; each hit's `timelinePeriod` is its
        period's index in `periods`.
      required:
      - dateField
      - start
      - end
      - periods
      - notes
      properties:
        dateField:
          type: string
          enum:
          - created
          - modified
        automatic:
          type: boolean
          description: |
            `true` when the caller left `timeline` out and the span was long enough to run as a
            timeline; `false` when the caller asked for it.
        start:
          type: string
          format: date
          description: First day of the span searched.
        end:
          type: string
          format: date
          description: Last day of the span searched, inclusive.
        periods:
          type: array
          items:
            $ref: '#/components/schemas/SemanticSearchTimelinePeriod'
        notes:
          type: array
          items:
            type: string
          description: Plain-language notes on the span, such as the start chosen when none was given.
    SemanticSearchTimelinePeriod:
      type: object
      additionalProperties: false
      required:
      - label
      - start
      - end
      - records
      - matches
      properties:
        label:
          type: string
          example: March 2026 (2026-03-01 to 2026-03-31)
        start:
          type: string
          format: date
          nullable: true
          description: First day of the period. `null` for the last bucket, of matches whose record has no source date.
        end:
          type: string
          format: date
          nullable: true
        records:
          type: integer
          minimum: 0
          description: Records with matches in this period. `0` may only mean nothing matched this query then.
        matches:
          type: integer
          minimum: 0
        searchFailed:
          type: boolean
          description: This period's own search failed; any matches shown come from the search of the whole span.
        searchIncomplete:
          type: string
          description: The search reached only part of the index for this period, so a record missing here may still exist.
    SemanticSearchExecuteResponse:
      type: object
      additionalProperties: false
      description: |
        Immediate POST `/search` response: persisted search id plus the raw retrieval payload.
        `searchId` is absent when the request set `saveHistory` to `false`.
        SDK-oriented modeling: named fields only at this level; dynamic-key maps inside `searchResponse` use
        `additionalProperties` with a `$ref` (e.g. `virtual_to_record_map`) rather than boolean `additionalProperties: true`,
        so generated clients retain typed values where possible.
      required:
      - searchResponse
      properties:
        searchId:
          type: string
          format: objectId
          description: The saved search, for `GET /search/{searchId}`. Absent when `saveHistory` is `false`.
        searchResponse:
          $ref: '#/components/schemas/SemanticSearchAiResponse'
    PersistedSemanticSearchBoundingBox:
      type: object
      additionalProperties: false
      description: |
        Bounding box subdocument embedded in persisted citation metadata.
        `boundingBoxSchema` does not set `_id: false`, so Mongoose auto-injects an `_id`.
      required:
      - _id
      - x
      - y
      properties:
        _id:
          type: string
          format: objectId
        x:
          type: number
        y:
          type: number
    PersistedSemanticSearchCitationMetadata:
      type: object
      additionalProperties: false
      description: |
        Citation metadata as persisted in MongoDB. Required fields mirror the
        Mongoose schema's `required: true` flags; the rest are optional and
        may come through as `null` because the AI retrieval service emits
        explicit nulls for absent fields.
      required:
      - orgId
      - mimeType
      - recordId
      - recordName
      - origin
      properties:
        orgId:
          type: string
        mimeType:
          type: string
        recordId:
          type: string
        recordName:
          type: string
        origin:
          type: string
        recordVersion:
          type: integer
          nullable: true
        extension:
          type: string
          nullable: true
        webUrl:
          type: string
          nullable: true
        previewRenderable:
          type: boolean
          nullable: true
        hideWeburl:
          type: boolean
          nullable: true
        connector:
          type: string
          nullable: true
        connectorId:
          type: string
          nullable: true
          description: |
            The connector instance the record came from. `connector` names only
            the kind of source (for example `SLACK`), which several instances can
            share. Absent on citations saved before this field was stored.
        connectorInstanceName:
          type: string
          nullable: true
          description: |
            The name the connector instance had when the answer was written.
            Absent on citations saved before this field was stored.
        recordType:
          type: string
          nullable: true
        blockNum:
          type: array
          nullable: true
          items:
            type: number
            nullable: true
        pageNum:
          type: array
          nullable: true
          items:
            type: number
            nullable: true
        sheetNum:
          type: number
          nullable: true
        sheetName:
          type: string
          nullable: true
        bounding_box:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/PersistedSemanticSearchBoundingBox'
        blockType:
          type: string
          nullable: true
          description: |
            Block type for this citation. Common values: `text`, `image`, `table_row`, `table`,
            `record_summary` (whole-record semantic summary chunk).
        blockText:
          type: string
          nullable: true
        departments:
          type: array
          nullable: true
          items:
            type: string
        languages:
          type: array
          nullable: true
          items:
            type: string
        topics:
          type: array
          nullable: true
          items:
            type: string
        updatedAt:
          type: string
          format: date-time
          nullable: true
          description: When the cited record was last updated at its source.
    PersistedSemanticSearchCitation:
      type: object
      additionalProperties: false
      description: |
        Populated citation document referenced from a persisted search.
        The controller strips `__v` via `populate({ select: '-__v' })`.
      required:
      - _id
      - content
      - chunkIndex
      - citationType
      - metadata
      - createdAt
      - updatedAt
      properties:
        _id:
          type: string
          format: objectId
        content:
          type: string
        chunkIndex:
          type: integer
        citationType:
          type: string
        metadata:
          $ref: '#/components/schemas/PersistedSemanticSearchCitationMetadata'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PersistedSemanticSearchSharedWithEntry:
      type: object
      additionalProperties: false
      description: |
        Entry inside `sharedWith[]`: one user the search is shared with and
        the access level they were given.
      required:
      - userId
      - accessLevel
      properties:
        _id:
          type: string
          format: objectId
          description: |
            Identifier of this share entry, generated when the entry is
            stored. It identifies the entry, not the user — use `userId`
            for the user.
        userId:
          type: string
          format: objectId
          description: User the search is shared with.
        accessLevel:
          type: string
          enum:
          - read
          - write
          description: Access granted to that user.
    PersistedSemanticSearch:
      type: object
      additionalProperties: false
      description: |
        Persisted search document as returned to clients.
        `records` is a string-valued map: each value is `JSON.stringify(<record>)`,
        keyed by the source record's `_id` or `_key`. Clients must `JSON.parse`
        each value to recover the underlying record object (whose shape resembles
        `SemanticSearchGraphRecord`). This intentionally differs from the
        `searchResponse.records` array on the POST `/search` response, which is
        passed through from the retrieval service untouched.
      required:
      - _id
      - __v
      - query
      - limit
      - orgId
      - userId
      - citationIds
      - records
      - isShared
      - sharedWith
      - isArchived
      - createdAt
      - updatedAt
      properties:
        _id:
          type: string
          format: objectId
        __v:
          type: integer
        query:
          type: string
        limit:
          type: integer
        orgId:
          type: string
          format: objectId
        userId:
          type: string
          format: objectId
        citationIds:
          type: array
          description: |
            For a search shared with the viewer, a hit the viewer cannot read is a
            `RedactedSource`.
          items:
            anyOf:
            - $ref: '#/components/schemas/PersistedSemanticSearchCitation'
            - $ref: '#/components/schemas/RedactedSource'
        records:
          type: object
          description: |
            Map of source-record id (or `_key`) to a JSON-stringified record object.
            Clients must `JSON.parse` each value before reading fields.
          additionalProperties:
            type: string
        isShared:
          type: boolean
        shareLink:
          type: string
          description: Set once the search has been shared via `/search/{searchId}/share`.
        sharedWith:
          type: array
          items:
            $ref: '#/components/schemas/PersistedSemanticSearchSharedWithEntry'
        isArchived:
          type: boolean
        archivedBy:
          type: string
          format: objectId
          nullable: true
          description: |
            User ID of the last user who archived this row, or `null` after
            an unarchive cleared the archive state. Absent on rows that have
            never been archived. Currently-archived rows cannot reach this
            endpoint because `buildFilter` enforces `isArchived: false`.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PersistedSemanticSearchEnvelope:
      type: array
      description: |
        GET `/search/{searchId}` calls `Model.find()` (not `findOne()`) and sends
        the result as-is, so the wire format is an array of zero or one
        persisted search docs. A non-existent id returns `200 []`, **not** `404`.
      items:
        $ref: '#/components/schemas/PersistedSemanticSearch'
    SemanticSearchHistoryItem:
      type: object
      additionalProperties: false
      description: |
        One persisted search row as returned by `GET /search`. Mirrors the
        persisted search document except `citationIds` is an array of
        ObjectId strings (citations are not populated on the list endpoint,
        unlike `GET /search/{searchId}`).

        `shareLink` is absent from the JSON when the search has not been
        shared. `archivedBy` is `null` on rows that were previously archived
        and then unarchived, and absent on rows that have never been
        archived. The list endpoint already filters out currently-archived
        rows, so a string user-id value never appears here in practice.
      required:
      - _id
      - __v
      - query
      - limit
      - orgId
      - userId
      - citationIds
      - records
      - isShared
      - sharedWith
      - isArchived
      - createdAt
      - updatedAt
      properties:
        _id:
          type: string
          format: objectId
        __v:
          type: integer
        query:
          type: string
        limit:
          type: integer
        orgId:
          type: string
          format: objectId
        userId:
          type: string
          format: objectId
        citationIds:
          type: array
          items:
            type: string
            format: objectId
          description: |
            Hit ids. For a search shared with the viewer the ids are not returned
            (they cannot be checked against the viewer's access), so the array is empty.
        records:
          type: object
          description: |
            Map of source-record id (or `_key`) to `JSON.stringify(<record>)`.
            Clients must `JSON.parse` each value to recover the underlying
            record object. Populated at write-time in the POST `/search` handler.
          additionalProperties:
            type: string
        isShared:
          type: boolean
        shareLink:
          type: string
          description: Set once the search has been shared via `/search/{searchId}/share`.
        sharedWith:
          type: array
          items:
            $ref: '#/components/schemas/PersistedSemanticSearchSharedWithEntry'
        isArchived:
          type: boolean
        archivedBy:
          type: string
          format: objectId
          nullable: true
          description: |
            User ID of the last user who archived this row, or `null` after
            an unarchive cleared the archive state. Absent on rows that have
            never been archived.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    SemanticSearchHistoryPagination:
      type: object
      additionalProperties: false
      description: |
        Pagination block emitted by `buildPaginationMetadata` (utils.ts:417).
        `totalPages` is `Math.ceil(totalCount / limit)`, so an empty result
        has `totalPages: 0`, not `1`.
      required:
      - page
      - limit
      - totalCount
      - totalPages
      - hasNextPage
      - hasPrevPage
      properties:
        page:
          type: integer
        limit:
          type: integer
        totalCount:
          type: integer
        totalPages:
          type: integer
        hasNextPage:
          type: boolean
        hasPrevPage:
          type: boolean
    SemanticSearchHistoryAppliedDateRange:
      type: object
      additionalProperties: false
      description: |
        Echoed back only when the caller passed `startDate` and/or `endDate`.
        Each bound is an ISO 8601 string when set; the field is absent when
        the corresponding query param was omitted (utils.ts:480-486 reads
        `appliedFilters.createdAt.$gte?.toISOString()` directly, so missing
        bounds become `undefined` and drop out of the JSON).
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
    SemanticSearchHistoryFiltersApplied:
      type: object
      additionalProperties: false
      description: |
        Echo of which filters the caller actually supplied, built by
        `buildFiltersMetadata` (utils.ts:430-486). `page` and `limit` always
        appear because they are normalised to defaults before being recorded,
        so `filters` is never empty and `values` always contains at least
        `{ page, limit }`. Other keys appear only when the matching query
        param was non-empty (or, for `dateRange`, when `createdAt` was set
        on the Mongo filter).

        `values` keys are scalar strings rather than typed primitives
        (`'true'`/`'false'`, `'5'`, etc.) because they are passed through
        from `req.query` as Express parsed them — only `page` and `limit`
        are coerced to integers via `safeParsePagination`.
      required:
      - filters
      - values
      properties:
        filters:
          type: array
          items:
            type: string
            enum:
            - page
            - limit
            - search
            - shared
            - tags
            - minMessages
            - sortBy
            - sortOrder
            - startDate
            - endDate
            - messageType
            - dateRange
        values:
          type: object
          additionalProperties: false
          properties:
            page:
              type: integer
            limit:
              type: integer
            search:
              type: string
            shared:
              type: string
            tags:
              type: string
            minMessages:
              type: string
            sortBy:
              type: string
            sortOrder:
              type: string
            startDate:
              type: string
            endDate:
              type: string
            messageType:
              type: string
            dateRange:
              $ref: '#/components/schemas/SemanticSearchHistoryAppliedDateRange'
    SemanticSearchHistoryFilterToggle:
      type: object
      additionalProperties: false
      description: |
        Generic "filter X is available, current value is Y" block used for
        `shared`, `tags`, `minMessages`, `search`, and `messageType`. Either
        `type` (free-form value) or `values` (enum of allowed strings) is
        present, not both. `current` is the caller-supplied value passed
        through from `req.query`, hence string-or-null even when `type` is
        `'number'`.
      required:
      - description
      - current
      - applied
      properties:
        type:
          type: string
        values:
          type: array
          items:
            type: string
        description:
          type: string
        current:
          type: string
          nullable: true
        applied:
          type: boolean
    SemanticSearchHistoryPaginationField:
      type: object
      additionalProperties: false
      required:
      - type
      - current
      - min
      - max
      - default
      - description
      - applied
      properties:
        type:
          type: string
        current:
          type: integer
        min:
          type: integer
        max:
          type: integer
        default:
          type: integer
        description:
          type: string
        applied:
          type: boolean
    SemanticSearchHistorySortField:
      type: object
      additionalProperties: false
      description: |
        Used for `available.sorting.{sortBy,sortOrder}` and
        `available.sortingMessages.{sortBy,sortOrder}`. The `applied` flag
        is present on `sorting.*` and absent on `sortingMessages.*`, so it
        is optional here.
      required:
      - values
      - default
      - description
      - current
      properties:
        values:
          type: array
          items:
            type: string
        default:
          type: string
        description:
          type: string
        current:
          type: string
        applied:
          type: boolean
    SemanticSearchHistoryDateRange:
      type: object
      additionalProperties: false
      required:
      - type
      - description
      - format
      - current
      - applied
      properties:
        type:
          type: string
        description:
          type: string
        format:
          type: string
        current:
          type: object
          additionalProperties: false
          required:
          - start
          - end
          properties:
            start:
              type: string
              nullable: true
            end:
              type: string
              nullable: true
        applied:
          type: boolean
    SemanticSearchHistoryFiltersAvailable:
      type: object
      additionalProperties: false
      description: |
        Catalogue of filters the endpoint supports, plus their current values
        and `applied` flags. Built by `buildFiltersMetadata` (utils.ts:430-624).
      required:
      - shared
      - tags
      - minMessages
      - search
      - pagination
      - sorting
      - dateFilters
      - messageFilters
      - sortingMessages
      properties:
        shared:
          $ref: '#/components/schemas/SemanticSearchHistoryFilterToggle'
        tags:
          $ref: '#/components/schemas/SemanticSearchHistoryFilterToggle'
        minMessages:
          $ref: '#/components/schemas/SemanticSearchHistoryFilterToggle'
        search:
          $ref: '#/components/schemas/SemanticSearchHistoryFilterToggle'
        pagination:
          type: object
          additionalProperties: false
          required:
          - page
          - limit
          properties:
            page:
              $ref: '#/components/schemas/SemanticSearchHistoryPaginationField'
            limit:
              $ref: '#/components/schemas/SemanticSearchHistoryPaginationField'
        sorting:
          type: object
          additionalProperties: false
          required:
          - sortBy
          - sortOrder
          properties:
            sortBy:
              $ref: '#/components/schemas/SemanticSearchHistorySortField'
            sortOrder:
              $ref: '#/components/schemas/SemanticSearchHistorySortField'
        dateFilters:
          type: object
          additionalProperties: false
          required:
          - dateRange
          properties:
            dateRange:
              $ref: '#/components/schemas/SemanticSearchHistoryDateRange'
        messageFilters:
          type: object
          additionalProperties: false
          required:
          - messageType
          properties:
            messageType:
              $ref: '#/components/schemas/SemanticSearchHistoryFilterToggle'
        sortingMessages:
          type: object
          additionalProperties: false
          required:
          - sortBy
          - sortOrder
          properties:
            sortBy:
              $ref: '#/components/schemas/SemanticSearchHistorySortField'
            sortOrder:
              $ref: '#/components/schemas/SemanticSearchHistorySortField'
    SemanticSearchHistoryFilters:
      type: object
      additionalProperties: false
      required:
      - applied
      - available
      properties:
        applied:
          $ref: '#/components/schemas/SemanticSearchHistoryFiltersApplied'
        available:
          $ref: '#/components/schemas/SemanticSearchHistoryFiltersAvailable'
    SemanticSearchHistoryMeta:
      type: object
      additionalProperties: false
      description: |
        `requestId` comes from `req.context?.requestId` and is omitted from
        the JSON when upstream middleware did not set it.
      required:
      - timestamp
      - duration
      properties:
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        duration:
          type: integer
    SemanticSearchHistoryResponse:
      type: object
      additionalProperties: false
      description: |
        Envelope returned by `GET /search`. The handler runs `find()` plus
        `countDocuments()` in parallel and assembles `{ searchHistory,
        pagination, filters, meta }` (es_controller.ts:3925-3973).
      required:
      - searchHistory
      - pagination
      - filters
      - meta
      properties:
        searchHistory:
          type: array
          items:
            $ref: '#/components/schemas/SemanticSearchHistoryItem'
        pagination:
          $ref: '#/components/schemas/SemanticSearchHistoryPagination'
        filters:
          $ref: '#/components/schemas/SemanticSearchHistoryFilters'
        meta:
          $ref: '#/components/schemas/SemanticSearchHistoryMeta'
    AgentKnowledgeFiltersParsed:
      type: object
      additionalProperties: false
      description: |
        What a knowledge source is limited to. With both lists empty the agent
        searches the whole source; otherwise it searches only the listed
        record groups, folders and records, each with everything under it, and
        a selection made in a chat must lie under them. On GET, `filtersParsed`
        is this shape parsed from the stored `filters` JSON string.

        On create and update, `filters` may be this object or its JSON text.
        The two lists must hold valid UUIDs, at most 200 across both; a value
        that cannot be read is refused with 400 rather than saved as "no
        limit", and so is a limit that covers more nodes than one search may
        (50,000 by default). A stored limit that cannot be read limits the
        source to nothing.
      properties:
        recordGroups:
          type: array
          items:
            type: string
          description: Record-group ids (e.g. Confluence spaces, Jira projects), each with the groups nested in it. Not set for KB (Collection) entries — a KB is identified by its own `connectorId`; an id equal to a source's `connectorId` is ignored.
        records:
          type: array
          items:
            type: string
          description: Folder or record ids, each with everything under it.
        nodes:
          type: array
          description: Names of the ids above, for display. Not used for search.
          items:
            type: object
            additionalProperties: false
            required:
            - id
            - name
            - nodeType
            properties:
              id:
                type: string
              name:
                type: string
              nodeType:
                type: string
                description: '`recordGroup`, `folder` or `record`.'
    Toolset:
      type: object
      additionalProperties: false
      description: |
        Toolset instance linked to an agent, as projected by the graph store on
        `GET /agents/{agentKey}` and `GET /agents`. Multiple instances of the
        same integration type are distinguished by `instanceId` and optional
        `instanceName`.
      properties:
        _key:
          type: string
          description: Toolset instance node key in the backing graph store.
        name:
          allOf:
          - $ref: '#/components/schemas/AgentCreateToolsetName'
          description: Integration / toolset type key.
        displayName:
          type: string
          description: Human-readable toolset product label (for example `Jira` or `Slack`).
        type:
          type: string
        instanceId:
          type: string
          nullable: true
          description: |
            Admin-created toolset instance id. `null` when the toolset was
            attached to the agent without an instance.
        instanceName:
          type: string
          nullable: true
          description: |
            Human-readable instance label (e.g. sidebar instance name). `null`
            when the toolset was attached without an instance.
        selectedTools:
          type: array
          nullable: true
          description: |
            Tool names explicitly selected for this toolset instance, when the
            instance was created with a subset selection. `null`/absent when the
            instance exposes all of the toolset's tools.
          items:
            type: string
        tools:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              _key:
                type: string
                description: Tool node key in the backing graph store.
              name:
                type: string
              fullName:
                type: string
              toolsetName:
                type: string
                description: Toolset type key the tool belongs to.
              description:
                type: string
              deprecated:
                type: boolean
                readOnly: true
                description: |
                  Server-stamped on `GET /agents/{agentKey}`: `true` when the
                  tool's `fullName` is no longer in the runtime tool registry
                  (its `@tool` was removed). Read-only; ignored on create/update
                  bodies. Not stamped on the `GET /agents` list projection.
    McpServer:
      type: object
      additionalProperties: false
      description: |
        MCP server instance linked to an agent, as projected by the graph
        store on `GET /agents/{agentKey}` and `GET /agents` — same shape as
        `Toolset`. MCP server nodes carry no secrets, only the attach-time
        snapshot of `instanceId`/`typeId`/`name`.
      properties:
        _key:
          type: string
          description: MCP server instance node key in the backing graph store.
        name:
          type: string
          description: MCP server attachment name (attach-time snapshot).
        displayName:
          type: string
          description: Human-readable MCP server product label (for example `Jira MCP`).
        typeId:
          type: string
          description: Catalog server type id, when this instance came from a registered template.
        instanceId:
          type: string
          description: Admin-created MCP server instance id.
        tools:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              _key:
                type: string
                description: Tool node key in the backing graph store.
              name:
                type: string
              fullName:
                type: string
              description:
                type: string
    AgentFilters:
      description: |
        Knowledge scope filter as stored on the graph edge. The Node `getAgent`
        handler proxies this field unchanged from the AI service (only `agent.id`
        is stripped). May be a JSON string (typical graph storage) or an object.
        Prefer `filtersParsed` on GET for a guaranteed parsed object with the
        same keys as the object branch below.
      oneOf:
      - $ref: '#/components/schemas/AgentKnowledgeFiltersParsed'
      - type: string
        description: JSON-encoded filter object (graph storage format).
    Knowledge:
      type: object
      additionalProperties: false
      description: |
        Knowledge connector / indexed scope linked to an agent, as projected by
        the graph store on `GET /agents/{agentKey}` and `GET /agents`.
      properties:
        _key:
          type: string
        connectorId:
          type: string
        name:
          type: string
        type:
          type: string
        displayName:
          type: string
        filters:
          $ref: '#/components/schemas/AgentFilters'
        filtersParsed:
          readOnly: true
          description: |
            Server-derived read-only object parsed from the stored
            `filters` JSON by the graph provider on GET (Neo4j / Arango).
            Empty object when `filters` is missing or invalid JSON.
          allOf:
          - $ref: '#/components/schemas/AgentKnowledgeFiltersParsed'
    AgentSkill:
      type: object
      additionalProperties: false
      description: |
        A skill linked to the agent, as returned by the agent detail graph
        projection. Flat by design — a skill carries no sub-entities analogous
        to a toolset's tools. Fields other than `name` are read straight off
        the skill document and are null when unset.
      required:
      - name
      properties:
        name:
          type: string
          description: Unique skill name, used to reference the skill on agent create/update.
        description:
          type: string
          nullable: true
        category:
          type: string
          nullable: true
        subcategory:
          type: string
          nullable: true
        version:
          type: string
          nullable: true
        status:
          type: string
          nullable: true
          description: Lifecycle state of the skill — `active`, `deprecated`, or `disabled`. `candidate` is a learning-loop record state, not an assignable skill, and is not returned here.
    Agent:
      type: object
      additionalProperties: false
      description: |
        Detailed agent projection returned by agent detail-style endpoints such
        as `GET /agents/{agentKey}`.
      properties:
        _id:
          type: string
          description: Full document id in the backing graph store.
          example: agentInstances/e6f848ca-e2ab-4594-9925-e1136629f474
        _key:
          type: string
          description: Stable agent key used in route params.
          example: e6f848ca-e2ab-4594-9925-e1136629f474
        _rev:
          type: string
          description: Backend document revision token.
          example: _lkNlcOm---
        name:
          type: string
          description: Display name of the agent
          example: Customer Support Assistant
        description:
          type: string
          description: What this agent is designed to do
        systemPrompt:
          type: string
          description: System instructions that define agent behavior
        createdBy:
          type: string
          format: objectId
          description: MongoDB user ID of the agent creator
        startMessage:
          type: string
          description: Initial greeting shown when a conversation with this agent starts
        instructions:
          type: string
          nullable: true
          description: Additional agent execution instructions
        models:
          type: array
          description: |
            Configured model entries for this agent.
          example:
          - modelType: llm
            provider: azureOpenAI
            modelName: gpt-5.6-luna
            modelKey: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
            isMultimodal: true
            isReasoning: true
            isDefault: true
            modelFriendlyName: GPT 5.4 mini
          items:
            oneOf:
            - type: string
            - type: object
              additionalProperties: false
              properties:
                modelKey:
                  type: string
                modelName:
                  type: string
                provider:
                  type: string
                isReasoning:
                  type: boolean
                isMultimodal:
                  type: boolean
                isDefault:
                  type: boolean
                modelType:
                  type: string
                  description: |
                    Model category. Must be `llm` for agent model entries (same
                    value as `ModelType` for LLMs; string only — enum is not used here).
                  example: llm
                modelFriendlyName:
                  type: string
                defaultReasoningEffort:
                  type: string
                  enum:
                  - none
                  - low
                  - medium
                  - high
                  - max
                  description: The model's own reasoning effort, read from its stored configuration. It applies only when the chat request sets no `reasoningEffort` and the agent has no `defaultReasoningEffort`. Omitted when nothing valid is stored; `none` is a legacy value that runs as `low`.
                  example: low
        usesOrgDefault:
          type: boolean
          description: |
            True when this agent has no models configured and will use the
            organization's default LLM (marked `isDefault: true` in the AI
            models configuration) at chat time. Derived from `models` being
            empty — not persisted separately.
        toolsets:
          type: array
          description: |
            Toolset instances linked to the agent (GET /agents/{agentKey} graph projection).
            Multiple instances of the same integration type are distinguished by `instanceId`
            and optional `instanceName`.
          items:
            $ref: '#/components/schemas/Toolset'
        mcpServers:
          type: array
          description: |
            MCP server instances linked to the agent (GET /agents/{agentKey} graph
            projection). Same shape/semantics as `toolsets`, keyed by `instanceId`.
          items:
            $ref: '#/components/schemas/McpServer'
        knowledge:
          type: array
          description: Knowledge connectors and indexed scopes linked to the agent
          items:
            $ref: '#/components/schemas/Knowledge'
        skills:
          type: array
          description: Skills linked to the agent via `agentHasSkill` edges
          items:
            $ref: '#/components/schemas/AgentSkill'
        shareWithOrg:
          type: boolean
          description: Whether the agent is shared with the whole organization
        webSearch:
          type: object
          additionalProperties: false
          nullable: true
          description: Web search provider attached to this agent. Null when none is configured.
          properties:
            provider:
              type: string
              description: Provider identifier (e.g. "tavily", "serper", "exa", "duckduckgo")
            providerKey:
              type: string
            providerLabel:
              type: string
          required:
          - provider
          example:
            provider: serper
        defaultReasoningEffort:
          type: string
          nullable: true
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: Agent-level reasoning effort used when a chat request omits its own. Null when unset.
        apiToolsetTools:
          type: array
          maxItems: 500
          description: |
            API toolset operations the agent may call, each `<toolsetId>:<operation>`
            (see `/api-toolsets`). A service-account agent may only use toolsets with a
            shared credential.
          items:
            type: string
            pattern: ^[0-9a-f]{32}:[A-Za-z0-9_-]{1,64}$
        sendUserContext:
          type: boolean
          description: |
            When true (default), the agent's system prompt includes the current
            user's name, email, and organization. When false, the agent relies
            on tools, actions, and knowledge sources without that profile data.
        tags:
          type: array
          items:
            type: string
          description: Free-form agent tags.
        createdAtTimestamp:
          type: integer
          format: int64
          description: Unix epoch timestamp in milliseconds when the agent was created.
        updatedAtTimestamp:
          type: integer
          format: int64
          description: Unix epoch timestamp in milliseconds when the agent was last updated.
        updatedBy:
          type: string
          nullable: true
          description: User id of the last updater, if present.
        isActive:
          type: boolean
          description: Whether the agent is active.
        isDeleted:
          type: boolean
          description: Whether the agent has been soft-deleted.
        isServiceAccount:
          type: boolean
          description: Whether this agent is a service-account agent.
        serviceAccountUserId:
          type: string
          nullable: true
          description: |
            The `userId` of the service account this agent searches knowledge
            as, or null when it searches as its creator. Only set on a
            service-account agent.
        access_type:
          type: string
          description: How the user can access this agent.
          example: INDIVIDUAL
        user_role:
          type: string
          description: Effective role of the current user on this agent.
          example: OWNER
        can_view:
          type: boolean
          description: Effective permission to view the agent.
        can_share:
          type: boolean
          description: Effective permission to share the agent.
        can_edit:
          type: boolean
          description: Effective permission to edit the agent.
        can_delete:
          type: boolean
          description: Effective permission to delete the agent.
      required:
      - _id
      - _key
      - createdAtTimestamp
      - createdBy
      - isActive
      - isDeleted
      - isServiceAccount
      - models
      - name
      - tags
      - updatedAtTimestamp
      - shareWithOrg
      - knowledge
      - toolsets
      - mcpServers
      - skills
      - can_view
      - can_share
      - can_edit
      - can_delete
      - user_role
      - access_type
    AgentListItem:
      type: object
      additionalProperties: false
      description: |
        Agent projection returned by `GET /agents`.

        This is the list-view envelope item emitted by the Python backend and
        forwarded by the Node gateway. It is not the full detail projection
        used by `GET /agents/{agentKey}`.
      properties:
        _id:
          type: string
          description: Full document id in the backing graph store.
          example: agentInstances/e6f848ca-e2ab-4594-9925-e1136629f474
        _key:
          type: string
          description: Stable agent key used in route params.
          example: e6f848ca-e2ab-4594-9925-e1136629f474
        _rev:
          type: string
          description: Backend document revision token.
          example: _lkNlcOm---
        createdAtTimestamp:
          type: integer
          format: int64
          description: Unix epoch timestamp in milliseconds when the agent was created.
        createdBy:
          type: string
          description: MongoDB user ID of the agent creator
        description:
          type: string
          nullable: true
          description: Short human-readable description of the agent.
        instructions:
          type: string
          nullable: true
          description: Additional execution instructions stored on the agent.
        isActive:
          type: boolean
          description: Whether the agent is active.
        isDeleted:
          type: boolean
          description: Whether the agent has been soft-deleted.
        isServiceAccount:
          type: boolean
          description: Whether this agent is a service-account agent.
        serviceAccountUserId:
          type: string
          nullable: true
          description: |
            The `userId` of the service account this agent searches knowledge
            as, or null when it searches as its creator. Only set on a
            service-account agent.
        models:
          type: array
          description: |
            Model entries configured on the agent.

            For `GET /agents`, the backend returns the stored normalized string
            representation, typically `modelKey_modelName`.
          items:
            type: string
        name:
          type: string
          description: Display name of the agent.
        startMessage:
          type: string
          nullable: true
          description: Greeting shown at conversation start.
        systemPrompt:
          type: string
          nullable: true
          description: System prompt stored on the agent.
        tags:
          type: array
          items:
            type: string
          description: Free-form agent tags.
        updatedAtTimestamp:
          type: integer
          format: int64
          description: Unix epoch timestamp in milliseconds when the agent was last updated.
        updatedBy:
          type: string
          nullable: true
          description: User id of the last updater, if present.
        usesOrgDefault:
          type: boolean
          description: |
            True when this agent has no models configured and will use the
            organization's default LLM (marked `isDefault: true` in the AI
            models configuration) at chat time. Derived from `models` being
            empty — not persisted separately.
        webSearch:
          type: object
          additionalProperties: false
          nullable: true
          description: |
            Web-search provider attachment for this agent, or `null` when none is attached.

            For `GET /agents`, the response formatter always emits `provider`.
            It may also emit `providerKey` and `providerLabel` when those values
            were present on the stored attachment. It does not emit `iconPath`
            on this response path.
          properties:
            provider:
              type: string
            providerKey:
              type: string
            providerLabel:
              type: string
        defaultReasoningEffort:
          type: string
          nullable: true
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: Agent-level reasoning effort used when a chat request omits its own. Null when unset.
        apiToolsetTools:
          type: array
          maxItems: 500
          description: |
            API toolset operations the agent may call, each `<toolsetId>:<operation>`
            (see `/api-toolsets`). A service-account agent may only use toolsets with a
            shared credential.
          items:
            type: string
            pattern: ^[0-9a-f]{32}:[A-Za-z0-9_-]{1,64}$
        sendUserContext:
          type: boolean
          description: When false, this agent omits user name/email/org from its system prompt.
        shareWithOrg:
          type: boolean
          description: Whether the agent is shared with the organization.
        toolsets:
          type: array
          description: |
            Toolset instances linked to the agent. Same projection as
            `GET /agents/{agentKey}`; the backend builds it from the graph edges
            for each agent on the returned page.
          items:
            $ref: '#/components/schemas/Toolset'
        mcpServers:
          type: array
          description: |
            MCP server instances linked to the agent. Same projection as
            `GET /agents/{agentKey}`; the backend builds it from the graph
            edges for each agent on the returned page.
          items:
            $ref: '#/components/schemas/McpServer'
        knowledge:
          type: array
          description: |
            Knowledge connectors and indexed scopes linked to the agent. Same
            projection as `GET /agents/{agentKey}`; the backend builds it from
            the graph edges for each agent on the returned page.
          items:
            $ref: '#/components/schemas/Knowledge'
        can_view:
          type: boolean
          description: Effective permission to view the agent.
        can_share:
          type: boolean
          description: Effective permission to share the agent.
        can_edit:
          type: boolean
          description: Effective permission to edit the agent.
        can_delete:
          type: boolean
          description: Effective permission to delete the agent.
        user_role:
          type: string
          description: Effective role of the current user on this agent.
          example: OWNER
        access_type:
          type: string
          description: How the user can access this agent.
          example: INDIVIDUAL
      required:
      - _id
      - _key
      - createdAtTimestamp
      - createdBy
      - isActive
      - isDeleted
      - isServiceAccount
      - models
      - name
      - tags
      - updatedAtTimestamp
      - shareWithOrg
      - toolsets
      - mcpServers
      - knowledge
      - can_view
      - can_share
      - can_edit
      - can_delete
      - user_role
      - access_type
    AgentListPagination:
      type: object
      additionalProperties: false
      description: Pagination block returned by `GET /agents`.
      required:
      - currentPage
      - limit
      - totalItems
      - totalPages
      - hasNext
      - hasPrev
      properties:
        currentPage:
          type: integer
          description: Current 1-based page number.
          example: 1
        limit:
          type: integer
          description: Page size actually applied by the backend.
          example: 20
        totalItems:
          type: integer
          description: Total number of matching agents across all pages.
          example: 2
        totalPages:
          type: integer
          description: Total number of pages for the current query.
          example: 1
        hasNext:
          type: boolean
          description: Whether a later page exists.
          example: false
        hasPrev:
          type: boolean
          description: Whether an earlier page exists.
          example: false
    AgentListResponse:
      type: object
      additionalProperties: false
      description: |
        Paginated response returned by `GET /agents`.

        The Node gateway forwards the Python backend response on success. If
        the backend returns a non-200 response, the gateway still returns HTTP
        200 with `success: true`, an empty `agents` array, and a zeroed
        pagination block derived from the requested `page` / `limit`.
      required:
      - success
      - agents
      - pagination
      properties:
        success:
          type: boolean
          example: true
        agents:
          type: array
          items:
            $ref: '#/components/schemas/AgentListItem'
        pagination:
          $ref: '#/components/schemas/AgentListPagination'
    GetAgentResponse:
      type: object
      additionalProperties: false
      description: |
        Success envelope returned by `GET /agents/{agentKey}`.

        The Node gateway forwards the backend response as an envelope with a
        top-level status/message and the detailed agent projection nested under
        `agent`.
      required:
      - status
      - message
      - agent
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Agent retrieved successfully
        agent:
          $ref: '#/components/schemas/Agent'
    AgentCreateModelEntry:
      description: |
        Accepted model entry for `POST /agents/create`.
        The gateway accepts either a non-empty string model entry or an object entry
        with a required `modelKey`.

        The `models` array itself is optional and may be empty (the agent then uses
        the organization's default LLM). When the array is non-empty, it must include
        at least one object entry with `isReasoning: true`. String-only entries are
        schema-valid but, if present without any reasoning-flagged object entry, are
        rejected at the gateway with HTTP 400.
      oneOf:
      - type: string
        minLength: 1
        pattern: \S
      - type: object
        additionalProperties: false
        required:
        - modelKey
        properties:
          modelKey:
            type: string
            minLength: 1
            pattern: \S
            description: Surrounding whitespace is trimmed; a blank key is refused with `400`.
          modelName:
            type: string
          provider:
            type: string
          isReasoning:
            type: boolean
    AgentCreateToolRef:
      type: object
      additionalProperties: false
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          pattern: \S
          description: Surrounding whitespace is trimmed; a blank name is refused with `400`.
        fullName:
          type: string
          minLength: 1
          pattern: \S
          description: Surrounding whitespace is trimmed; a blank value is refused with `400`.
        description:
          type: string
          maxLength: 10000
    AgentCreateToolsetName:
      type: string
      description: Registered toolset name (lowercase) accepted by the create-agent gateway.
      enum:
      - calendar
      - clickup
      - confluence
      - confluencedatacenter
      - docs
      - drive
      - github
      - gmail
      - jira
      - jiradatacenter
      - lumos
      - mariadb
      - onedrive
      - outlook
      - redshift
      - salesforce
      - sharepoint
      - sheets
      - slack
      - teams
      - zoom
    AgentCreateToolset:
      type: object
      additionalProperties: false
      required:
      - name
      properties:
        name:
          allOf:
          - $ref: '#/components/schemas/AgentCreateToolsetName'
          description: |
            Toolset name. Surrounding whitespace is trimmed before the check, so
            `"  slack  "` is accepted.
        displayName:
          type: string
          maxLength: 200
        type:
          type: string
          maxLength: 100
        instanceId:
          type: string
          maxLength: 256
        instanceName:
          type: string
          maxLength: 200
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AgentCreateToolRef'
    AgentCreateKnowledge:
      type: object
      additionalProperties: false
      required:
      - connectorId
      properties:
        connectorId:
          type: string
          minLength: 1
          pattern: \S
          description: Surrounding whitespace is trimmed; a blank id is refused with `400`.
        filters:
          description: |
            The source's limit, as an object or its JSON text. An empty string or an empty
            array means no limit. A non-empty array, `null`, or text that is not the JSON of
            an object is refused with `400` (`VALIDATION_ERROR`, "Knowledge filters must be
            an object, with recordGroups and records as lists of ids").
          oneOf:
          - $ref: '#/components/schemas/AgentKnowledgeFiltersParsed'
          - type: string
          - type: array
            maxItems: 0
            items: {}
    AgentCreateWebSearch:
      description: |
        Web-search attachment for an agent. Accepts a provider string, an object
        with at least a `provider` field, or `null`. The provider string and
        `provider` are trimmed; an empty or blank value is refused with `400`.
      anyOf:
      - type: string
        nullable: true
        minLength: 1
        pattern: \S
      - type: object
        additionalProperties: false
        properties:
          provider:
            type: string
            minLength: 1
            pattern: \S
          providerKey:
            type: string
            maxLength: 256
          providerLabel:
            type: string
            maxLength: 200
          iconPath:
            type: string
            maxLength: 500
        required:
        - provider
    AgentSkillAssignment:
      type: object
      additionalProperties: false
      description: Reference to an existing skill assigned to an agent.
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
          pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
          description: Lowercase skill name using single hyphens between segments.
    AgentCreateRequest:
      type: object
      additionalProperties: false
      description: |
        Body of `POST /agents/create`. Fields the gateway validator does not know
        (at the top level and inside `models[]`, `webSearch`, `knowledge[]`,
        `toolsets[]` and `mcpServers[]`) are dropped before the request reaches the
        AI backend; they are not refused.
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          pattern: \S
          description: |
            Agent display name. Surrounding whitespace is trimmed; a blank name is
            refused with `400` (`VALIDATION_ERROR`, "Name is required").
          example: Product Support Agent
        description:
          type: string
          maxLength: 100000
          description: What the agent does
        startMessage:
          type: string
          maxLength: 100000
          description: Initial greeting shown when conversation starts
        systemPrompt:
          type: string
          maxLength: 100000
          description: System instructions for the agent
        instructions:
          type: string
          maxLength: 100000
          description: Additional agent execution instructions
        models:
          type: array
          minItems: 0
          default: []
          description: |
            Agent model configuration entries. Optional — an agent created without
            any models (an empty array or an omitted field) uses the organization's
            default LLM at chat time. A non-empty list must hold at least one object
            entry with `isReasoning: true`; otherwise the gateway answers `400`
            (`VALIDATION_ERROR` on `models`, "At least one reasoning model is
            required").
          items:
            $ref: '#/components/schemas/AgentCreateModelEntry'
        tags:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 100
        shareWithOrg:
          type: boolean
          default: false
          description: Share agent with the organization
        isServiceAccount:
          type: boolean
          default: false
          description: Create the agent as a service-account agent
        serviceAccountUserId:
          type: string
          description: |
            The `userId` of the service account this agent should search
            knowledge as, as returned by the service accounts API. Only valid
            on a service-account agent: sending it without `isServiceAccount`
            is refused rather than ignored, so a request cannot quietly create
            an agent that searches as its creator. Omit it and the agent
            searches as its creator.
            Whitespace around it is removed first; 1-128 characters.
          minLength: 1
          maxLength: 128
        toolsets:
          type: array
          maxItems: 100
          description: Toolsets attached to the agent (instance-aware)
          items:
            $ref: '#/components/schemas/AgentCreateToolset'
        knowledge:
          type: array
          maxItems: 100
          description: Knowledge sources connected to the agent
          items:
            $ref: '#/components/schemas/AgentCreateKnowledge'
        skills:
          type: array
          maxItems: 100
          description: Existing skills to assign to the agent
          items:
            $ref: '#/components/schemas/AgentSkillAssignment'
        mcpServers:
          type: array
          maxItems: 50
          description: |
            MCP server instances attached to the agent. Two entries with the same
            `typeId` are refused with `400` (`VALIDATION_ERROR` on
            `mcpServers.<index>.typeId`); entries without a `typeId` are exempt.
            The instance is not looked up when the agent is saved.
          items:
            $ref: '#/components/schemas/AgentMcpServerRef'
        webSearch:
          $ref: '#/components/schemas/AgentCreateWebSearch'
        defaultReasoningEffort:
          type: string
          nullable: true
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: Agent-level reasoning effort used when a chat request omits its own.
        apiToolsetTools:
          type: array
          maxItems: 500
          description: |
            API toolset operations the agent may call, each `<toolsetId>:<operation>`
            (see `/api-toolsets`). A service-account agent may only use toolsets with a
            shared credential.
          items:
            type: string
            pattern: ^[0-9a-f]{32}:[A-Za-z0-9_-]{1,64}$
        sendUserContext:
          type: boolean
          default: true
          description: |
            When true (default), include the current user's name, email, and
            organization in this agent's system prompt. When false, omit that
            profile data.
    AgentCreateWarning:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
        error:
          type: string
    AgentCreateResponseTool:
      type: object
      additionalProperties: false
      required:
      - name
      - fullName
      - key
      properties:
        name:
          type: string
        fullName:
          type: string
        key:
          type: string
    AgentCreateResponseToolset:
      type: object
      additionalProperties: false
      required:
      - name
      - displayName
      - key
      - tools
      properties:
        name:
          $ref: '#/components/schemas/AgentCreateToolsetName'
        displayName:
          type: string
          description: Human-readable toolset product label (for example `Jira` or `Slack`).
        key:
          type: string
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AgentCreateResponseTool'
    AgentCreateResponseMcpServerTool:
      type: object
      additionalProperties: false
      required:
      - name
      - fullName
      - key
      properties:
        name:
          type: string
        fullName:
          type: string
        key:
          type: string
    AgentCreateResponseMcpServer:
      type: object
      additionalProperties: false
      required:
      - name
      - displayName
      - key
      - tools
      properties:
        name:
          type: string
        displayName:
          type: string
          description: Human-readable MCP server product label (for example `Jira MCP`).
        key:
          type: string
        tools:
          type: array
          items:
            $ref: '#/components/schemas/AgentCreateResponseMcpServerTool'
    AgentCreateResponseKnowledge:
      type: object
      additionalProperties: false
      required:
      - connectorId
      - key
      - filters
      properties:
        connectorId:
          type: string
        key:
          type: string
        filters:
          oneOf:
          - type: object
            additionalProperties: true
          - type: string
          - type: array
            items: {}
    AgentCreateResponseSkill:
      type: object
      additionalProperties: false
      description: |
        A skill linked to the agent at creation time. Creating or updating an
        agent only links edges to skills that already exist and never writes a
        skill document, so only the name is echoed back here.
      required:
      - name
      properties:
        name:
          type: string
    AgentCreateResponseAgent:
      type: object
      additionalProperties: false
      required:
      - _key
      - name
      - description
      - startMessage
      - systemPrompt
      - instructions
      - models
      - tags
      - webSearch
      - isActive
      - isServiceAccount
      - createdBy
      - updatedBy
      - createdAtTimestamp
      - updatedAtTimestamp
      - isDeleted
      - toolsets
      - mcpServers
      - knowledge
      - skills
      properties:
        _key:
          type: string
        name:
          type: string
        description:
          type: string
        startMessage:
          type: string
        systemPrompt:
          type: string
        instructions:
          type: string
          nullable: true
        models:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        webSearch:
          anyOf:
          - type: object
            nullable: true
            additionalProperties: false
            properties:
              provider:
                type: string
              providerKey:
                type: string
              providerLabel:
                type: string
        defaultReasoningEffort:
          type: string
          nullable: true
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: Agent-level reasoning effort used when a chat request omits its own. Null when unset.
        apiToolsetTools:
          type: array
          maxItems: 500
          description: |
            API toolset operations the agent may call, each `<toolsetId>:<operation>`
            (see `/api-toolsets`). A service-account agent may only use toolsets with a
            shared credential.
          items:
            type: string
            pattern: ^[0-9a-f]{32}:[A-Za-z0-9_-]{1,64}$
        sendUserContext:
          type: boolean
          description: When false, this agent omits user name/email/org from its system prompt.
        isActive:
          type: boolean
        isServiceAccount:
          type: boolean
        serviceAccountUserId:
          type: string
          nullable: true
          description: |
            The `userId` of the service account this agent searches knowledge
            as, or null when it searches as its creator. Only set on a
            service-account agent.
        createdBy:
          type: string
        updatedBy:
          type: string
          nullable: true
        createdAtTimestamp:
          type: integer
        updatedAtTimestamp:
          type: integer
        isDeleted:
          type: boolean
        toolsets:
          type: array
          items:
            $ref: '#/components/schemas/AgentCreateResponseToolset'
        mcpServers:
          type: array
          items:
            $ref: '#/components/schemas/AgentCreateResponseMcpServer'
        knowledge:
          type: array
          items:
            $ref: '#/components/schemas/AgentCreateResponseKnowledge'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/AgentCreateResponseSkill'
    AgentCreateResponse:
      type: object
      additionalProperties: false
      required:
      - status
      - message
      - agent
      properties:
        status:
          type: string
          enum:
          - success
          - partial_success
        message:
          type: string
        agent:
          $ref: '#/components/schemas/AgentCreateResponseAgent'
        warnings:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/AgentCreateWarning'
    AgentUpdateRequest:
      type: object
      additionalProperties: false
      description: |
        Partial update payload for `PUT /agents/{agentKey}`.

        Every field is optional — only the fields present in the request body
        are updated. `models` may be omitted, set to an empty array to clear
        the agent's models (reverting it to the organization's default LLM at
        chat time), or set to a non-empty array. When a non-empty array is
        provided, the gateway Zod middleware (mirroring the Python backend)
        requires at least one object entry with `isReasoning: true`.

        Fields the gateway validator does not know are dropped before the
        request reaches the AI backend; they are not refused.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          pattern: \S
          description: |
            Agent display name. Surrounding whitespace is trimmed; a blank name is
            refused with `400` (`VALIDATION_ERROR`).
          example: Renamed Agent
        description:
          type: string
          maxLength: 100000
          description: What the agent does
        startMessage:
          type: string
          maxLength: 100000
          description: Initial greeting shown when conversation starts
        systemPrompt:
          type: string
          maxLength: 100000
          description: System instructions for the agent
        instructions:
          type: string
          maxLength: 100000
          description: Additional agent execution instructions
        models:
          type: array
          minItems: 0
          description: |
            Agent model configuration entries. Optional. An empty array clears the
            agent's models so it falls back to the organization's default LLM.
            A non-empty list must hold at least one object entry with
            `isReasoning: true`; otherwise the gateway answers `400`
            (`VALIDATION_ERROR` on `models`).
          items:
            $ref: '#/components/schemas/AgentCreateModelEntry'
        tags:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 100
        shareWithOrg:
          type: boolean
          default: false
          description: Share agent with the organization
        isServiceAccount:
          type: boolean
          default: false
          description: Mark agent as a service account
        serviceAccountUserId:
          type: string
          nullable: true
          description: |
            The `userId` of the service account this agent should search
            knowledge as. Only valid on a service-account agent, checked
            against what the agent will be once the request is applied, so one
            request may convert an agent and bind it. Null is accepted on any
            agent and clears the binding, going back to searching as the
            agent's creator.
            Whitespace around it is removed first; 1-128 characters.
          minLength: 1
          maxLength: 128
        toolsets:
          type: array
          maxItems: 100
          description: Toolsets attached to the agent (instance-aware)
          items:
            $ref: '#/components/schemas/AgentCreateToolset'
        knowledge:
          type: array
          maxItems: 100
          description: Knowledge sources connected to the agent
          items:
            $ref: '#/components/schemas/AgentCreateKnowledge'
        skills:
          type: array
          maxItems: 100
          description: |
            Complete replacement set of skills assigned to the agent. Send
            an empty array to clear all skill assignments.
          items:
            $ref: '#/components/schemas/AgentSkillAssignment'
        mcpServers:
          type: array
          maxItems: 50
          description: |
            MCP server instances attached to the agent. Two entries with the same
            `typeId` are refused with `400` (`VALIDATION_ERROR` on
            `mcpServers.<index>.typeId`); entries without a `typeId` are exempt.
          items:
            $ref: '#/components/schemas/AgentMcpServerRef'
        webSearch:
          $ref: '#/components/schemas/AgentCreateWebSearch'
        defaultReasoningEffort:
          type: string
          nullable: true
          enum:
          - none
          - low
          - medium
          - high
          - max
          description: Agent-level reasoning effort used when a chat request omits its own.
        apiToolsetTools:
          type: array
          maxItems: 500
          description: |
            API toolset operations the agent may call, each `<toolsetId>:<operation>`
            (see `/api-toolsets`). A service-account agent may only use toolsets with a
            shared credential.
          items:
            type: string
            pattern: ^[0-9a-f]{32}:[A-Za-z0-9_-]{1,64}$
        sendUserContext:
          type: boolean
          description: |
            When true (default), include the current user's name, email, and
            organization in this agent's system prompt. When false, omit that
            profile data.
    AgentUpdateResponse:
      type: object
      additionalProperties: false
      required:
      - status
      - message
      properties:
        status:
          type: string
          enum:
          - success
        message:
          type: string
          example: Agent updated successfully
    AgentDeleteResponse:
      type: object
      additionalProperties: false
      required:
      - status
      - message
      - deleted
      properties:
        status:
          type: string
          enum:
          - success
        message:
          type: string
          example: Agent deleted successfully
        deleted:
          type: object
          additionalProperties: false
          required:
          - agents
          - toolsets
          - tools
          - knowledge
          - edges
          properties:
            agents:
              type: integer
              minimum: 0
              example: 1
            toolsets:
              type: integer
              minimum: 0
              example: 0
            tools:
              type: integer
              minimum: 0
              example: 0
            knowledge:
              type: integer
              minimum: 0
              example: 0
            edges:
              type: integer
              minimum: 0
              example: 0
    AgentConversation:
      type: object
      description: |
        A conversation with a specific AI agent. Similar to regular conversations
        but tied to an agent's configuration and capabilities.
      properties:
        _id:
          type: string
          format: objectId
        agentKey:
          type: string
          description: The agent this conversation is with
        userId:
          type: string
          format: objectId
        orgId:
          type: string
          format: objectId
        title:
          type: string
        initiator:
          type: string
          format: objectId
          description: User who started the conversation.
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        status:
          type: string
          enum:
          - None
          - Inprogress
          - Complete
          - Failed
          - Stopped
          description: Same values as `Conversation.status`.
        failReason:
          type: string
          description: Error description, populated only when `status` is `Failed`.
        modelInfo:
          $ref: '#/components/schemas/ConversationModelInfo'
        isShared:
          type: boolean
        shareLink:
          type: string
          description: Shareable link, present only when the conversation is shared.
        sharedWith:
          type: array
          items:
            type: object
            properties:
              userId:
                type: string
              accessLevel:
                type: string
                enum:
                - read
                - write
        isArchived:
          type: boolean
          description: Whether this conversation is archived.
        archivedBy:
          type: string
          format: objectId
          nullable: true
          description: User who archived the conversation. Absent on rows that were never archived.
        isDeleted:
          type: boolean
          description: Whether this conversation has been soft-deleted.
        deletedBy:
          type: string
          format: objectId
          nullable: true
          description: User who soft-deleted the conversation. Absent on live rows.
        conversationErrors:
          type: array
          description: Errors recorded against this conversation (e.g. failed message generations).
          items:
            type: object
            required:
            - message
            properties:
              _id:
                type: string
                format: objectId
              message:
                type: string
              errorType:
                type: string
              timestamp:
                type: string
                format: date-time
              messageId:
                type: string
                format: objectId
              stack:
                type: string
              metadata:
                type: object
                additionalProperties: true
                description: Free-form map of error context values.
        metadata:
          type: object
          additionalProperties: true
          description: Free-form metadata map attached to the conversation.
        conversationSource:
          type: string
          enum:
          - agent_chat
          description: Always `agent_chat` for agent conversations.
        compactedSummary:
          type: string
          description: |
            Summary of older turns, present only once the conversation has
            been compacted.
        compactedAtTurnIndex:
          type: integer
          description: Turn index up to which `compactedSummary` covers the conversation.
        compactedAtTimestamp:
          type: integer
          format: int64
          description: Unix timestamp (ms) of the last compaction.
        lastActivityAt:
          type: integer
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        __v:
          type: integer
          description: Document version counter of the backing store.
        projectId:
          type: string
          format: objectId
          nullable: true
          description: The project this agent conversation is linked to, if any.
        projectVisibility:
          type: string
          enum:
          - private
          - project
          nullable: true
          description: |
            Only meaningful when `projectId` is set. `project` exposes the
            conversation to every member of the linked project.
    AgentConversationListItem:
      type: object
      additionalProperties: false
      description: |
        Conversation summary returned by `GET /agents/{agentKey}/conversations`.
        The handler excludes `messages` and `__v` from both result sets. Rows
        in `sharedWithMeConversations` also omit `sharedWith` because the
        secondary query explicitly deselects that field before serialization.
      properties:
        _id:
          type: string
          format: objectId
        agentKey:
          type: string
          description: Agent identifier from the route path
        userId:
          type: string
          format: objectId
        orgId:
          type: string
          format: objectId
        title:
          type: string
        initiator:
          type: string
          format: objectId
        status:
          type: string
          enum:
          - None
          - Inprogress
          - Complete
          - Failed
          - Stopped
        failReason:
          type: string
        modelInfo:
          $ref: '#/components/schemas/ConversationModelInfo'
        isShared:
          type: boolean
        shareLink:
          type: string
        sharedWith:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              _id:
                type: string
                format: objectId
              userId:
                type: string
                format: objectId
              accessLevel:
                type: string
                enum:
                - read
                - write
        isArchived:
          type: boolean
        archivedBy:
          type: string
          format: objectId
          nullable: true
        archivedAt:
          type: string
          format: date-time
          description: |
            Present on archived conversation endpoints. Derived from the
            document `updatedAt` timestamp when the archive response is built.
        isDeleted:
          type: boolean
        deletedBy:
          type: string
          format: objectId
          nullable: true
        conversationErrors:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              _id:
                type: string
                format: objectId
                description: Sub-document identifier auto-assigned by MongoDB.
              message:
                type: string
              errorType:
                type: string
              timestamp:
                type: string
                format: date-time
              messageId:
                type: string
                format: objectId
              stack:
                type: string
              metadata:
                type: object
                additionalProperties: true
        conversationSource:
          type: string
          enum:
          - agent_chat
        lastActivityAt:
          type: integer
          format: int64
          description: Epoch milliseconds of the latest activity on the thread
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        isOwner:
          type: boolean
          readOnly: true
          description: |
            Computed per request. `true` when the conversation `initiator`
            matches the authenticated user.
        accessLevel:
          type: string
          enum:
          - read
          - write
          readOnly: true
          description: |
            Computed per request from `sharedWith`; defaults to `read` when no
            explicit share grant is attached to the serialized row.
        sharedBy:
          $ref: '#/components/schemas/ConversationSharedBy'
        projectId:
          type: string
          format: objectId
          nullable: true
          description: The project this agent conversation is linked to, if any.
        projectVisibility:
          type: string
          enum:
          - private
          - project
          nullable: true
          description: |
            Only meaningful when `projectId` is set. `project` exposes the
            conversation to every member of the linked project.
    AgentConversationListResponse:
      type: object
      additionalProperties: false
      description: |
        Envelope returned by `GET /agents/{agentKey}/conversations`.
        `conversations` contains rows owned by the caller for the agent;
        `sharedWithMeConversations` contains rows shared with the caller for
        the same agent. Both arrays use the same pagination and sort inputs,
        but `pagination.totalCount` and `totalPages` are computed only from
        `conversations` because the handler counts the owned-query filter only.
      required:
      - conversations
      - sharedWithMeConversations
      - pagination
      - filters
      - meta
      properties:
        conversations:
          type: array
          items:
            $ref: '#/components/schemas/AgentConversationListItem'
        sharedWithMeConversations:
          type: array
          items:
            $ref: '#/components/schemas/AgentConversationListItem'
        pagination:
          $ref: '#/components/schemas/SemanticSearchHistoryPagination'
        filters:
          $ref: '#/components/schemas/SemanticSearchHistoryFilters'
        meta:
          $ref: '#/components/schemas/SemanticSearchHistoryMeta'
    AgentArchivedConversationGroup:
      type: object
      additionalProperties: false
      description: |
        Archived conversations for a single agent, sliced to the first page
        of the per-agent archive query (limit 5, sorted newest first).
      required:
      - agentKey
      - conversations
      - pagination
      properties:
        agentKey:
          type: string
          description: Agent identifier the conversations belong to.
        conversations:
          type: array
          items:
            $ref: '#/components/schemas/AgentConversationListItem'
        pagination:
          $ref: '#/components/schemas/SemanticSearchHistoryPagination'
    AgentArchivedGroupsResponse:
      type: object
      additionalProperties: false
      description: |
        Response from `GET /agents/conversations/show/archives` — archived agent
        conversations grouped by `agentKey`, with agent-level pagination over
        the groups and a fixed slice of conversations under each agent.
      required:
      - groups
      - agentPagination
      - meta
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/AgentArchivedConversationGroup'
        agentPagination:
          $ref: '#/components/schemas/SemanticSearchHistoryPagination'
        meta:
          $ref: '#/components/schemas/RequestMeta'
    AgentArchivedConversationSummary:
      type: object
      additionalProperties: false
      description: |
        Archive counts and bounds for the current result page returned by
        `GET /agents/{agentKey}/conversations/show/archives`.
      properties:
        totalArchived:
          type: integer
          description: Total archived conversations matching the filter
        oldestArchive:
          type: string
          format: date-time
          description: Archive timestamp of the first item in the current page. Omitted when the page is empty.
        newestArchive:
          type: string
          format: date-time
          description: Archive timestamp of the last item in the current page. Omitted when the page is empty.
    AgentArchivedConversationListResponse:
      type: object
      additionalProperties: false
      description: |
        Envelope returned by `GET /agents/{agentKey}/conversations/show/archives`.
      required:
      - conversations
      - pagination
      - filters
      - summary
      - meta
      properties:
        conversations:
          type: array
          items:
            $ref: '#/components/schemas/AgentConversationListItem'
        pagination:
          $ref: '#/components/schemas/SemanticSearchHistoryPagination'
        filters:
          $ref: '#/components/schemas/SemanticSearchHistoryFilters'
        summary:
          $ref: '#/components/schemas/AgentArchivedConversationSummary'
        meta:
          $ref: '#/components/schemas/SemanticSearchHistoryMeta'
    RequestMeta:
      type: object
      additionalProperties: false
      description: Basic request metadata returned by the API.
      required:
      - timestamp
      - duration
      properties:
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        duration:
          type: integer
    ConversationTitleUpdateRequest:
      type: object
      additionalProperties: false
      required:
      - title
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 200
          pattern: \S
          description: |
            New title for the conversation. Surrounding whitespace is trimmed; a
            blank title is refused.
          example: ABC News Follow-up
    StoredAgentConversation:
      type: object
      additionalProperties: false
      description: |
        Stored agent conversation document returned by non-list endpoints.
      properties:
        _id:
          type: string
          format: objectId
        agentKey:
          type: string
        userId:
          type: string
          format: objectId
        orgId:
          type: string
          format: objectId
        title:
          type: string
        initiator:
          type: string
          format: objectId
        messages:
          type: array
          items:
            $ref: '#/components/schemas/Message'
        status:
          type: string
          enum:
          - None
          - Inprogress
          - Complete
          - Failed
          - Stopped
        failReason:
          type: string
        modelInfo:
          $ref: '#/components/schemas/ConversationModelInfo'
        isShared:
          type: boolean
        shareLink:
          type: string
        sharedWith:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              userId:
                type: string
                format: objectId
              accessLevel:
                type: string
                enum:
                - read
                - write
        isArchived:
          type: boolean
        archivedBy:
          type: string
          format: objectId
          nullable: true
        isDeleted:
          type: boolean
        deletedBy:
          type: string
          format: objectId
          nullable: true
        conversationErrors:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              _id:
                type: string
                format: objectId
              message:
                type: string
              errorType:
                type: string
              timestamp:
                type: string
                format: date-time
              messageId:
                type: string
                format: objectId
              stack:
                type: string
              metadata:
                type: object
                additionalProperties: true
        conversationSource:
          type: string
          enum:
          - agent_chat
        lastActivityAt:
          type: integer
          format: int64
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        __v:
          type: integer
    AgentConversationTitleUpdateResponse:
      type: object
      additionalProperties: false
      required:
      - conversation
      - meta
      properties:
        conversation:
          $ref: '#/components/schemas/StoredAgentConversation'
        meta:
          $ref: '#/components/schemas/RequestMeta'
    AgentConversationDeleteResponse:
      type: object
      additionalProperties: false
      description: |
        Envelope returned by `DELETE /agents/{agentKey}/conversations/{conversationId}`.
        When the conversation does not exist, belongs to a different agent, or
        was already deleted, the API still returns HTTP 200 with
        `conversation: null`.
      required:
      - message
      - conversation
      properties:
        message:
          type: string
          enum:
          - Conversation deleted successfully
        conversation:
          anyOf:
          - $ref: '#/components/schemas/StoredAgentConversation'
          - type: object
            nullable: true
            enum:
            - null
    AgentConversationDetailMessageCitation:
      type: object
      additionalProperties: false
      description: |
        Citation entry returned inside a conversation message after the
        handler populates `messages.citations.citationId` and rewrites each
        item to `{ citationId, citationData }`.
      properties:
        citationId:
          type: string
          format: objectId
        citationData:
          $ref: '#/components/schemas/Citation'
    AgentConversationDetailMessage:
      type: object
      additionalProperties: false
      description: |
        Message shape returned by `GET /agents/{agentKey}/conversations/{conversationId}`.
        The response spreads the stored message document and replaces
        `citations` with populated citation objects.
      properties:
        _id:
          type: string
          format: objectId
        messageType:
          type: string
          enum:
          - user_query
          - bot_response
          - error
          - feedback
          - system
          - tool_call
        content:
          type: string
        contentFormat:
          type: string
          enum:
          - MARKDOWN
          - JSON
          - HTML
        citations:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/AgentConversationDetailMessageCitation'
            - $ref: '#/components/schemas/RedactedSource'
        confidence:
          type: string
          enum:
          - Very High
          - High
          - Medium
          - Low
          - Unknown
          nullable: true
          description: |
            AI confidence in the answer. Present only on `bot_response` messages,
            and only when the model emitted a trailing confidence block.

            This field is now optional and nullable; it was previously always present and non-nullable. Treat a missing or `null` value as "no confidence reported" and guard before using it. Change effective in SDK v1.3.0 (v1.2.0 and earlier always populated it).
        followUpQuestions:
          type: array
          items:
            $ref: '#/components/schemas/FollowUpQuestion'
        feedback:
          type: array
          items:
            $ref: '#/components/schemas/MessageFeedback'
        referenceData:
          type: array
          description: |
            Reference identifiers surfaced from tool responses, used to scope
            follow-up queries.
          items:
            anyOf:
            - type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: Display name shown to the user.
                id:
                  type: string
                  description: Technical identifier (numeric ID, UUID, etc.).
                type:
                  type: string
                  description: Item type (e.g. `project`, `issue`, `file`, `notebook`, `page`).
                app:
                  type: string
                  description: |
                    Source application (e.g. `jira`, `confluence`, `sharepoint`,
                    `slack`, `drive`, `gmail`).
                webUrl:
                  type: string
                  description: URL to open the item in a browser.
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                  description: |
                    App-specific fields keyed by name (e.g. `key` for a Jira project,
                    `siteId` for a SharePoint document).
            - $ref: '#/components/schemas/RedactedSource'
        attachments:
          type: array
          description: |
            Files uploaded for this message turn (see
            `POST /agents/{agentKey}/conversations/attachments/upload`).
          items:
            $ref: '#/components/schemas/ChatAttachmentRef'
        tools:
          type: array
          description: Tool call results invoked during this message turn.
          items:
            $ref: '#/components/schemas/MessageToolCall'
        reasoning:
          type: array
          description: Persisted chain-of-thought for this turn.
          items:
            $ref: '#/components/schemas/MessageReasoningTurn'
        parts:
          type: array
          description: Ordered agent-activity transcript for this turn.
          items:
            $ref: '#/components/schemas/MessagePart'
        modelInfo:
          $ref: '#/components/schemas/ConversationModelInfo'
        appliedFilters:
          $ref: '#/components/schemas/AppliedFilters'
        metadata:
          type: object
          additionalProperties: false
          properties:
            processingTimeMs:
              type: number
            modelVersion:
              type: string
            aiTransactionId:
              type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    AgentConversationDetailPagination:
      type: object
      additionalProperties: false
      description: |
        Message pagination returned inside the `conversation` object. The
        handler paginates backwards from the end of the stored message array,
        then sorts the selected page in memory before serialization.
      required:
      - page
      - limit
      - totalCount
      - totalPages
      - hasNextPage
      - hasPrevPage
      - messageRange
      properties:
        page:
          type: integer
        limit:
          type: integer
        totalCount:
          type: integer
        totalPages:
          type: integer
        hasNextPage:
          type: boolean
          description: True when older messages exist outside the returned page
        hasPrevPage:
          type: boolean
          description: True when newer messages exist outside the returned page
        messageRange:
          type: object
          additionalProperties: false
          required:
          - start
          - end
          properties:
            start:
              type: integer
            end:
              type: integer
    AgentConversationDetailAccess:
      type: object
      additionalProperties: false
      properties:
        isOwner:
          type: boolean
        accessLevel:
          type: string
          enum:
          - read
          - write
    AgentConversationDetail:
      type: object
      additionalProperties: false
      description: |
        Reduced conversation view returned by the by-id GET route. This is
        not the raw `AgentConversation` document shape: fields like `agentKey`,
        `userId`, `orgId`, `conversationSource`, and root-level `messages`
        metadata outside the selected slice are omitted.

        `sharedWith` is the owner's list of recipients, so it is present only for the
        owner. A recipient gets `sharedBy` (who shared the chat) instead.
      required:
      - id
      - createdAt
      - isShared
      - messages
      - pagination
      - access
      properties:
        id:
          type: string
          format: objectId
        title:
          type: string
        initiator:
          type: string
          format: objectId
        createdAt:
          type: string
          format: date-time
        isShared:
          type: boolean
        sharedWith:
          type: array
          items:
            type: object
            additionalProperties: false
            properties:
              _id:
                type: string
                format: objectId
              userId:
                type: string
                format: objectId
              accessLevel:
                type: string
                enum:
                - read
                - write
        status:
          type: string
          enum:
          - None
          - Inprogress
          - Complete
          - Failed
          - Stopped
        failReason:
          type: string
        sharedBy:
          $ref: '#/components/schemas/ConversationSharedBy'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/AgentConversationDetailMessage'
        modelInfo:
          $ref: '#/components/schemas/ConversationModelInfo'
        pagination:
          $ref: '#/components/schemas/AgentConversationDetailPagination'
        access:
          $ref: '#/components/schemas/AgentConversationDetailAccess'
    AgentConversationDetailMeta:
      type: object
      additionalProperties: false
      description: |
        Request-scoped metadata returned by the by-id GET route. `requestId`
        is omitted when upstream middleware did not attach one.
      required:
      - timestamp
      - duration
      - conversationId
      - messageCount
      properties:
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        duration:
          type: integer
        conversationId:
          type: string
          format: objectId
        messageCount:
          type: integer
    AgentConversationDetailResponse:
      type: object
      additionalProperties: false
      description: |
        Envelope returned by `GET /agents/{agentKey}/conversations/{conversationId}`.
      required:
      - conversation
      - filters
      - meta
      properties:
        conversation:
          $ref: '#/components/schemas/AgentConversationDetail'
        filters:
          $ref: '#/components/schemas/SemanticSearchHistoryFilters'
        meta:
          $ref: '#/components/schemas/AgentConversationDetailMeta'
    AgentConversationArchiveMeta:
      type: object
      additionalProperties: false
      description: |
        Request-scoped metadata returned by the archive route. `requestId` is
        omitted when upstream middleware did not attach one.
      required:
      - timestamp
      - duration
      properties:
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        duration:
          type: integer
    AgentConversationArchiveResponse:
      type: object
      additionalProperties: false
      description: |
        Envelope returned by `POST /agents/{agentKey}/conversations/{conversationId}/archive`.
      required:
      - id
      - status
      - archivedBy
      - archivedAt
      - meta
      properties:
        id:
          type: string
          format: objectId
        status:
          type: string
          enum:
          - archived
        archivedBy:
          type: string
          format: objectId
        archivedAt:
          type: string
          format: date-time
        meta:
          $ref: '#/components/schemas/AgentConversationArchiveMeta'
    AgentConversationUnarchiveMeta:
      type: object
      additionalProperties: false
      description: |
        Request-scoped metadata returned by the unarchive route. `requestId` is
        omitted when upstream middleware did not attach one.
      required:
      - timestamp
      - duration
      properties:
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        duration:
          type: integer
    AgentConversationUnarchiveResponse:
      type: object
      additionalProperties: false
      description: |
        Envelope returned by `POST /agents/{agentKey}/conversations/{conversationId}/unarchive`.
      required:
      - id
      - status
      - unarchivedBy
      - unarchivedAt
      - meta
      properties:
        id:
          type: string
          format: objectId
        status:
          type: string
          enum:
          - unarchived
        unarchivedBy:
          type: string
          format: objectId
        unarchivedAt:
          type: string
          format: date-time
        meta:
          $ref: '#/components/schemas/AgentConversationUnarchiveMeta'
    AgentRegenerateSSEEvent:
      type: object
      additionalProperties: false
      description: |
        SSE event envelope for `POST /agents/{agentKey}/conversations/{conversationId}/message/{messageId}/regenerate`.
        AG-UI is the sole wire protocol.

        `event` carries the AG-UI type name and `data` is a JSON-encoded
        object that includes a `"type"` field matching `event`, plus
        type-specific fields. Stable gateway-generated top-level outcomes:

        - `RUN_FINISHED` returns `{ type, result }` where
          `result` is `{ conversation, recordsUsed, meta }` — the updated
          conversation plus request metadata after the regenerated response
          is persisted.
        - `RUN_ERROR` returns `{ type, message, code? }`. Conversation
          lookup failures, unauthorized conversation access, and regenerate
          rule failures such as "not the last message" are reported here.

        Other events are forwarded from the agent backend and should be
        treated as informational updates. Those forwarded lifecycle and
        child-run events may contain `runId`, `threadId`, and `parentRunId`;
        the gateway-generated root terminal event does not.
      properties:
        event:
          type: string
          enum:
          - RUN_STARTED
          - RUN_FINISHED
          - RUN_ERROR
          - STEP_STARTED
          - STEP_FINISHED
          - TEXT_MESSAGE_START
          - TEXT_MESSAGE_CONTENT
          - TEXT_MESSAGE_END
          - REASONING_START
          - REASONING_MESSAGE_START
          - REASONING_MESSAGE_CONTENT
          - REASONING_MESSAGE_END
          - REASONING_END
          - TOOL_CALL_START
          - TOOL_CALL_ARGS
          - TOOL_CALL_END
          - TOOL_CALL_RESULT
          - STATE_DELTA
          - STATE_SNAPSHOT
          - CUSTOM
          - HEARTBEAT
        data:
          type: string
          description: |
            JSON-encoded event payload. The decoded JSON includes a `"type"`
            field matching `event`, plus type-specific fields. Shape depends
            on `event`.
    SSEEvent:
      type: object
      description: |
        Server-Sent Event envelope for streaming chat responses. AG-UI is
        the sole wire protocol.

        `event` carries the AG-UI type name and `data` is a JSON-encoded
        object that includes a `"type"` field matching `event`, plus
        type-specific fields. Stable gateway-generated top-level outcomes:

        - `RUN_FINISHED` — `{ type, result }`; `result` carries the full
          persisted `conversation` and a `meta` block with `requestId`,
          `timestamp` and `duration`.
        - `RUN_ERROR` — `{ type, message, code? }`. The conversation row is
          marked FAILED before the stream closes.

        Forwarded upstream lifecycle or child-run events may contain `runId`,
        `threadId`, and `parentRunId`. Gateway-generated root terminal events
        do not. Clients should ignore unknown event names.
      properties:
        event:
          type: string
          enum:
          - RUN_STARTED
          - RUN_FINISHED
          - RUN_ERROR
          - STEP_STARTED
          - STEP_FINISHED
          - TEXT_MESSAGE_START
          - TEXT_MESSAGE_CONTENT
          - TEXT_MESSAGE_END
          - REASONING_START
          - REASONING_MESSAGE_START
          - REASONING_MESSAGE_CONTENT
          - REASONING_MESSAGE_END
          - REASONING_END
          - TOOL_CALL_START
          - TOOL_CALL_ARGS
          - TOOL_CALL_END
          - TOOL_CALL_RESULT
          - STATE_DELTA
          - STATE_SNAPSHOT
          - CUSTOM
          - HEARTBEAT
        data:
          type: string
          description: |
            JSON-encoded event payload. The decoded JSON includes a `"type"`
            field matching `event`, plus type-specific fields. Shape depends
            on `event`.
    ConversationStreamSSEEvent:
      type: object
      description: |
        Server-Sent Event envelope for public conversation streams using
        `agent`, `internal_search`, or `web_search`. AG-UI is the sole wire
        protocol.

        `event` carries the AG-UI type name and `data` is a JSON-encoded
        object that includes a `"type"` field matching `event`, plus
        type-specific fields. Universal `agent` mode may emit `STEP_STARTED`,
        `STEP_FINISHED`, and nested child-run events carrying `parentRunId`.
        Stable gateway-generated top-level outcomes:

        - `CUSTOM` (`name: "conversation_created"`) — fired once on
          connection. Carries the newly created `conversationId` and
          `title` so the client can link the stream to the new row before
          any tokens arrive.
        - `RUN_FINISHED` — fired once after the AI backend finishes.
          The gateway emits `{ type, result }`; `result` carries the full
          persisted `conversation` and a `meta` block.
        - `RUN_ERROR` — fired when the stream fails. Carries a `message`
          and optional `code`; the conversation row is marked FAILED
          before close.

        Forwarded upstream lifecycle or child-run events may contain `runId`,
        `threadId`, and `parentRunId`. Gateway-generated root terminal events
        do not.
        Clients should ignore unknown event names rather than treating them
        as errors.
      properties:
        event:
          type: string
          enum:
          - RUN_STARTED
          - RUN_FINISHED
          - RUN_ERROR
          - STEP_STARTED
          - STEP_FINISHED
          - TEXT_MESSAGE_START
          - TEXT_MESSAGE_CONTENT
          - TEXT_MESSAGE_END
          - REASONING_START
          - REASONING_MESSAGE_START
          - REASONING_MESSAGE_CONTENT
          - REASONING_MESSAGE_END
          - REASONING_END
          - TOOL_CALL_START
          - TOOL_CALL_ARGS
          - TOOL_CALL_END
          - TOOL_CALL_RESULT
          - STATE_DELTA
          - STATE_SNAPSHOT
          - CUSTOM
          - HEARTBEAT
        data:
          type: string
          description: |
            JSON-encoded event payload. The decoded JSON includes a `"type"`
            field matching `event`, plus type-specific fields. Shape depends
            on `event`. Forwarded lifecycle events may carry `runId`,
            `threadId`, and `parentRunId`.
    ConversationMessageStreamSSEEvent:
      type: object
      description: |
        Server-Sent Event envelope for public follow-up streams using `agent`,
        `internal_search`, or `web_search` on an existing conversation. AG-UI
        is the sole wire protocol.

        `event` carries the AG-UI type name and `data` is a JSON-encoded
        object that includes a `"type"` field matching `event`, plus
        type-specific fields. Universal `agent` mode may emit step and nested
        child-run events. Stable gateway-generated top-level outcomes:

        - `CUSTOM` (`name: "conversation_created"`) — fired once on
          connection.
        - `RUN_FINISHED` — fired once after the AI backend finishes.
          The gateway emits `{ type, result }`; `result` carries
          `{ conversation, recordsUsed, meta }`.
          `recordsUsed` is the count of citations attached to the new
          assistant message.
        - `RUN_ERROR` — fired when the stream fails. Carries a `message`
          and optional `code`; the conversation row is marked FAILED
          before close.

        Forwarded upstream lifecycle or child-run events may contain `runId`,
        `threadId`, and `parentRunId`. Gateway-generated root terminal events
        do not.
        Clients should ignore unknown event names rather than treating them
        as errors.
      properties:
        event:
          type: string
          enum:
          - RUN_STARTED
          - RUN_FINISHED
          - RUN_ERROR
          - STEP_STARTED
          - STEP_FINISHED
          - TEXT_MESSAGE_START
          - TEXT_MESSAGE_CONTENT
          - TEXT_MESSAGE_END
          - REASONING_START
          - REASONING_MESSAGE_START
          - REASONING_MESSAGE_CONTENT
          - REASONING_MESSAGE_END
          - REASONING_END
          - TOOL_CALL_START
          - TOOL_CALL_ARGS
          - TOOL_CALL_END
          - TOOL_CALL_RESULT
          - STATE_DELTA
          - STATE_SNAPSHOT
          - CUSTOM
          - HEARTBEAT
        data:
          type: string
          description: |
            JSON-encoded event payload. The decoded JSON includes a `"type"`
            field matching `event`, plus type-specific fields. Shape depends
            on `event`. Forwarded lifecycle events may carry `runId`,
            `threadId`, and `parentRunId`.
    AgentStreamSSEEvent:
      type: object
      description: |
        SSE event envelope for `POST /agents/{agentKey}/conversations/stream`.
        AG-UI is the sole wire protocol.

        `event` carries the AG-UI type name and `data` is a JSON-encoded
        object that includes a `"type"` field matching `event`, plus
        type-specific fields. The public route requires `chatMode: quick`.
        Forwarded lifecycle events may carry `runId`, `threadId`, and
        `parentRunId`; gateway-generated root terminal events do not.

        Stable gateway-generated top-level outcomes are `RUN_FINISHED` as
        `{ type, result }` and `RUN_ERROR` as `{ type, message, code? }`.
        Clients should ignore unknown event names rather than treating them
        as errors.
      properties:
        event:
          type: string
          enum:
          - RUN_STARTED
          - RUN_FINISHED
          - RUN_ERROR
          - STEP_STARTED
          - STEP_FINISHED
          - TEXT_MESSAGE_START
          - TEXT_MESSAGE_CONTENT
          - TEXT_MESSAGE_END
          - REASONING_START
          - REASONING_MESSAGE_START
          - REASONING_MESSAGE_CONTENT
          - REASONING_MESSAGE_END
          - REASONING_END
          - TOOL_CALL_START
          - TOOL_CALL_ARGS
          - TOOL_CALL_END
          - TOOL_CALL_RESULT
          - STATE_DELTA
          - STATE_SNAPSHOT
          - CUSTOM
          - HEARTBEAT
        data:
          type: string
          description: |
            JSON-encoded event payload. The decoded JSON includes a `"type"`
            field matching `event`, plus type-specific fields. Shape depends
            on `event`.
    AgentMessageStreamSSEEvent:
      type: object
      description: |
        Server-Sent Event envelope for `POST /agents/{agentKey}/conversations/{conversationId}/messages/stream`.
        AG-UI is the sole wire protocol.

        `event` carries the AG-UI type name and `data` is a JSON-encoded
        object that includes a `"type"` field matching `event`, plus
        type-specific fields. The public route requires `chatMode: quick`.
        Forwarded lifecycle events may carry `runId`, `threadId`, and
        `parentRunId`. Stable gateway-generated top-level outcomes:

        - `CUSTOM` (`name: "conversation_created"`) — fired once after the
          SSE stream opens.
        - `RUN_FINISHED` — fired once after the upstream AI's result is
          parsed, citations are saved, and the updated conversation is
          persisted. The gateway emits `{ type, result }`; `result` carries
          `{ conversation, recordsUsed, meta }`.
        - `RUN_ERROR` — fired for runtime failures after the stream has
          already started, including conversation lookup failures, upstream
          AI startup failures, save failures, and stream transport errors.

        Gateway-generated root terminal events do not contain `runId`,
        `threadId`, or `parentRunId`.
        Clients should ignore unknown event names rather than treating them
        as errors.
      properties:
        event:
          type: string
          enum:
          - RUN_STARTED
          - RUN_FINISHED
          - RUN_ERROR
          - STEP_STARTED
          - STEP_FINISHED
          - TEXT_MESSAGE_START
          - TEXT_MESSAGE_CONTENT
          - TEXT_MESSAGE_END
          - REASONING_START
          - REASONING_MESSAGE_START
          - REASONING_MESSAGE_CONTENT
          - REASONING_MESSAGE_END
          - REASONING_END
          - TOOL_CALL_START
          - TOOL_CALL_ARGS
          - TOOL_CALL_END
          - TOOL_CALL_RESULT
          - STATE_DELTA
          - STATE_SNAPSHOT
          - CUSTOM
          - HEARTBEAT
        data:
          type: string
          description: |
            JSON-encoded event payload. The decoded JSON includes a `"type"`
            field matching `event`, plus type-specific fields. Shape depends
            on `event`.
    ConnectorScope:
      type: string
      description: |
        Scope determines visibility and access control for connectors:<br>
        <ul>
        <li><code>team</code> - Available to all users in the organization (admin-only creation)</li>
        <li><code>personal</code> - Private to the creating user only</li>
        </ul>
      enum:
      - team
      - personal
      example: team
    ConnectorAuthType:
      type: string
      description: How a connector instance signs in to its source. Each connector type supports a subset; see `supportedAuthTypes` in the registry.
      enum:
      - OAUTH
      - OAUTH_ADMIN_CONSENT
      - API_TOKEN
      - BEARER_TOKEN
      - BASIC_AUTH
      - ACCESS_KEY
      - IAM_ROLE
      - ACCOUNT_KEY
      - CONNECTION_STRING
      - ENTRA_ID
      - CUSTOM
      - NONE
    ConnectorInstance:
      type: object
      description: 'A connector instance: its type''s registry entry plus the instance''s own state.'
      properties:
        _key:
          type: string
          description: Connector instance ID
          example: 7b387394-1248-4fb6-810d-e8ac9ac226eb
        name:
          type: string
          description: Instance name
          example: Company Google Drive
        type:
          type: string
          description: Connector type
          example: Drive Workspace
        appGroup:
          type: string
          description: Product family the connector belongs to
        supportedAuthTypes:
          type: array
          description: Authentication methods the connector type supports
          items:
            $ref: '#/components/schemas/ConnectorAuthType'
        appDescription:
          type: string
        appCategories:
          type: array
          items:
            type: string
        iconPath:
          type: string
          description: Path of the connector icon
        supportsRealtime:
          type: boolean
        supportsSync:
          type: boolean
        supportsAgent:
          type: boolean
        documentationLinks:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorDocumentationLink'
        isAdminAccessRequired:
          type: boolean
        personalConnectorType:
          type: string
          description: For a team connector type, its personal counterpart, if any
          nullable: true
        connectorInfo:
          type: string
          description: Guidance shown before setup
          nullable: true
        authType:
          type: string
          nullable: true
          description: |
            Authentication method chosen when the instance was created, one of
            the type's `supportedAuthTypes`.
          example: OAUTH
        scope:
          $ref: '#/components/schemas/ConnectorScope'
        isActive:
          type: boolean
          description: Sync is on
        isAgentActive:
          type: boolean
          description: Agents may use this connector
        isConfigured:
          type: boolean
          description: Sync settings are saved; sync can be enabled
        isAuthenticated:
          type: boolean
          description: OAuth sign-in has completed
        isLocked:
          type: boolean
          description: A sync or deletion holds the connector
        status:
          type: string
          description: Lifecycle status, for example SYNCING or DELETING
          nullable: true
          example: IDLE
        pendingFullSync:
          type: boolean
        desktopOnline:
          type: boolean
        ownerDeviceId:
          type: string
          description: Local FS only. The desktop device that owns this connector
          nullable: true
        ownerDeviceName:
          type: string
          description: Local FS only. Display name of the desktop device that owns this connector
          nullable: true
        createdBy:
          type: string
          nullable: true
        updatedBy:
          type: string
          description: Null for an instance nobody has updated, for example the personal KB connector
          nullable: true
        createdAtTimestamp:
          type: integer
          description: Epoch milliseconds
          format: int64
          nullable: true
        updatedAtTimestamp:
          type: integer
          description: Epoch milliseconds
          format: int64
          nullable: true
        lastSyncStartedAtTimestamp:
          type: integer
          format: int64
          nullable: true
          description: Epoch ms when the last sync run started; absent before the first run
        lastSyncFinishedAtTimestamp:
          type: integer
          format: int64
          nullable: true
          description: Epoch ms when the last sync run ended, however it ended; absent until a run ends
        lastSyncOutcome:
          type: string
          nullable: true
          enum:
          - succeeded
          - failed
          - stopped
          - skipped
          description: How the last sync run ended
        lastSyncSummary:
          type: object
          nullable: true
          additionalProperties: true
          description: 'What the last run did, in the connector''s own terms. For a Web connector: pagesSaved (written this run), pagesStored (kept after it, which Maximum pages caps), pagesVisited, failed, failedByStatus, robotsSkipped, noindexSkipped, skippedMaxPages, deferred, pruned, sitemapUrls, stopReason (max_pages, time_limit, stalled, rate_limited or null) and resumed.'
        actionItems:
          type: array
          description: What the connector's admin has to do, shown as an action-needed badge on the instance card. Written by the connector at the end of each sync and when its auth settings are saved; empty when nothing is needed.
          items:
            type: object
            required:
            - code
            - severity
            - title
            - message
            properties:
              code:
                type: string
                description: Identifies the item for the connector, e.g. certificate_sign_in
              severity:
                type: string
                enum:
                - warning
                - error
              title:
                type: string
              message:
                type: string
              action:
                type: string
                nullable: true
                enum:
                - authenticate
                description: Where in the connector panel it is done; authenticate opens the Authenticate tab
              docsUrl:
                type: string
                format: uri
                nullable: true
                description: The setup steps for it, on the docs site
        config:
          $ref: '#/components/schemas/ConnectorSchema'
    ConnectorConfig:
      type: object
      properties:
        connector_id:
          type: string
          description: Connector instance ID
        name:
          type: string
          description: Instance name
        type:
          type: string
          description: Connector type
        appGroup:
          type: string
        authType:
          type: string
          nullable: true
          description: Authentication method chosen when the instance was created
          example: OAUTH
        scope:
          $ref: '#/components/schemas/ConnectorScope'
        createdBy:
          type: string
          nullable: true
          description: User ID who created this instance
        updatedBy:
          type: string
          nullable: true
          description: User ID who last changed this instance
        appDescription:
          type: string
        appCategories:
          type: array
          items:
            type: string
        supportsRealtime:
          type: boolean
        supportsSync:
          type: boolean
        supportsAgent:
          type: boolean
        iconPath:
          type: string
        config:
          $ref: '#/components/schemas/ConnectorStoredConfig'
        isActive:
          type: boolean
        isConfigured:
          type: boolean
        isAuthenticated:
          type: boolean
        createdAtTimestamp:
          type: integer
          format: int64
          nullable: true
          description: Creation time, epoch milliseconds
        updatedAtTimestamp:
          type: integer
          format: int64
          nullable: true
          description: Last update time, epoch milliseconds
    ConnectorSchema:
      type: object
      description: 'Configuration form for a connector type: the auth fields per auth type, the sync strategies and settings, and the sync and indexing filters.'
      properties:
        iconPath:
          type: string
        supportsRealtime:
          type: boolean
        supportsSync:
          type: boolean
        supportsAgent:
          type: boolean
        hideConnector:
          type: boolean
          description: Whether the type is hidden from the registry listing
        permissionModel:
          type: string
          description: |
            How records of this connector get their per-user visibility:
            `RECORD_LEVEL` (per-record permissions from the source) or
            `APP_LEVEL` (everyone who can reach the connector sees every record).
          enum:
          - RECORD_LEVEL
          - APP_LEVEL
        isAdminAccessRequired:
          type: boolean
        personalConnectorType:
          type: string
          nullable: true
        supportsConnectionCheck:
          type: boolean
          description: Whether POST /connectors/registry/{connectorType}/test-connection works for this type
        documentationLinks:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorDocumentationLink'
        auth:
          type: object
          properties:
            supportedAuthTypes:
              type: array
              items:
                $ref: '#/components/schemas/ConnectorAuthType'
            schemas:
              type: object
              description: Auth form per auth type, keyed by ConnectorAuthType
              additionalProperties:
                $ref: '#/components/schemas/ConnectorAuthSchemaForType'
            values:
              type: object
              additionalProperties: true
              description: Default values, keyed by field name
            customFields:
              type: array
              items: {}
            customValues:
              type: object
              additionalProperties: true
            conditionalDisplay:
              type: object
              additionalProperties: true
              description: Rules that show a field only when another field has a given value, keyed by the field they apply to
            authorizeUrl:
              type: string
              description: Instance reads only
            tokenUrl:
              type: string
              description: Instance reads only
            oauthConfigs:
              type: object
              description: 'Instance reads only: provider endpoints per auth type'
              additionalProperties:
                type: object
                properties:
                  authorizeUrl:
                    type: string
                  tokenUrl:
                    type: string
                  redirectUri:
                    type: string
                  scopes:
                    type: array
                    items:
                      type: string
          description: Authentication form
        sync:
          type: object
          properties:
            supportedStrategies:
              type: array
              items:
                type: string
                enum:
                - MANUAL
                - SCHEDULED
                - WEBHOOK
            selectedStrategy:
              type: string
              enum:
              - MANUAL
              - SCHEDULED
              - WEBHOOK
              description: Strategy preselected in the form
            webhookConfig:
              type: object
              properties:
                supported:
                  type: boolean
                webhookUrl:
                  type: string
                events:
                  type: array
                  items:
                    type: string
                verificationToken:
                  type: string
                secretKey:
                  type: string
            scheduledConfig:
              type: object
              properties:
                intervalMinutes:
                  type: integer
                cronExpression:
                  type: string
                timezone:
                  type: string
                  example: UTC
                startTime:
                  type: integer
                nextTime:
                  type: integer
                endTime:
                  type: integer
                maxRepetitions:
                  type: integer
                repetitionCount:
                  type: integer
            realtimeConfig:
              type: object
              properties:
                supported:
                  type: boolean
                connectionType:
                  type: string
                  example: WEBSOCKET
            customFields:
              type: array
              items:
                $ref: '#/components/schemas/ConnectorSyncCustomField'
            customValues:
              type: object
              additionalProperties: true
            values:
              type: object
              additionalProperties: true
          description: Sync options
        filters:
          type: object
          properties:
            sync:
              $ref: '#/components/schemas/ConnectorFilterSection'
            indexing:
              $ref: '#/components/schemas/ConnectorFilterSection'
          description: Filters the connector offers
    ConnectorAuthConfig:
      type: object
      description: 'Auth settings, flat: send each field listed under `auth.schemas.<authType>.fields` in GET /connectors/registry/{connectorType}/schema by its `name`. For OAuth, an admin may send the OAuth app''s credentials here (the app is saved and linked), or anyone may send `oauthConfigId` to use a saved app.'
      additionalProperties: true
      properties:
        oauthConfigId:
          type: string
          description: A saved OAuth app (GET /oauth/{connectorType})
        oauthInstanceName:
          type: string
          description: Name for the OAuth app saved from inline credentials
        connectorScope:
          type: string
          description: Scope of the instance, as the frontend sends it; the server fills it in when absent
        authType:
          type: string
          description: |
            On `PUT /connectors/{connectorId}/config` only: must equal the
            instance's `authType`, which cannot be changed (`400` otherwise).
      example:
        baseUrl: https://mycompany.atlassian.net
        email: admin@mycompany.com
        apiToken: ATATT3x...
    ConnectorSyncConfig:
      type: object
      description: 'Sync strategy plus connector-specific sync settings, flat: send each field listed under `sync.customFields` in the registry schema by its `name`.'
      additionalProperties: true
      properties:
        selectedStrategy:
          type: string
          enum:
          - MANUAL
          - SCHEDULED
          - WEBHOOK
        scheduledConfig:
          type: object
          properties:
            intervalMinutes:
              type: integer
              minimum: 1
            timezone:
              type: string
              default: UTC
            startTime:
              type: integer
              description: Epoch milliseconds
            startDateTime:
              description: When the schedule starts, as the frontend sends it
          additionalProperties: true
        webhookConfig:
          type: object
          properties:
            webhookUrl:
              type: string
            events:
              type: array
              items:
                type: string
    ConnectorFiltersConfig:
      type: object
      properties:
        sync:
          type: object
          properties:
            values:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/ConnectorFilterValue'
        indexing:
          type: object
          properties:
            values:
              type: object
              additionalProperties:
                $ref: '#/components/schemas/ConnectorFilterValue'
    CreateConnectorRequest:
      type: object
      required:
      - connectorType
      - instanceName
      - scope
      properties:
        connectorType:
          type: string
          minLength: 1
          description: '`type` from the registry'
        instanceName:
          type: string
          minLength: 1
          pattern: \S
        scope:
          $ref: '#/components/schemas/ConnectorScope'
        authType:
          allOf:
          - $ref: '#/components/schemas/ConnectorAuthType'
          description: One of the type's `supportedAuthTypes`; defaults to the first
        config:
          type: object
          properties:
            auth:
              $ref: '#/components/schemas/ConnectorAuthConfig'
            sync:
              $ref: '#/components/schemas/ConnectorSyncConfig'
            filters:
              $ref: '#/components/schemas/ConnectorFiltersConfig'
        baseUrl:
          type: string
          description: Origin of the page the OAuth provider redirects back to. The redirect URI is `{baseUrl}/{redirectUri}`; defaults to the PipesHub frontend URL.
    UpdateConnectorConfigRequest:
      type: object
      description: Request to update connector configuration (partial updates supported)
      properties:
        auth:
          $ref: '#/components/schemas/ConnectorAuthConfig'
        sync:
          $ref: '#/components/schemas/ConnectorSyncConfig'
        filters:
          $ref: '#/components/schemas/ConnectorFiltersConfig'
        baseUrl:
          type: string
          description: |
            Base URL for self-hosted instances. Any string is accepted; it is
            not checked to be a URL.
          example: https://confluence.mycompany.com
    UpdateConnectorAuthRequest:
      type: object
      required:
      - auth
      properties:
        auth:
          $ref: '#/components/schemas/ConnectorAuthConfig'
        baseUrl:
          type: string
          description: Recomputes the OAuth redirect URI
    UpdateConnectorFiltersSyncRequest:
      type: object
      minProperties: 1
      description: At least one of `sync` and `filters`. `filters.sync` and `filters.indexing` replace the saved ones.
      properties:
        sync:
          $ref: '#/components/schemas/ConnectorSyncConfig'
        filters:
          $ref: '#/components/schemas/ConnectorFiltersConfig'
      anyOf:
      - required:
        - sync
      - required:
        - filters
    SaveConnectorFiltersRequest:
      type: object
      description: |
        Request to save filter selections for a connector. Fields other than
        `filters` are dropped without an error.
      required:
      - filters
      properties:
        filters:
          type: object
          description: Filter values to save (structure depends on connector's filter schema). Must not be empty.
          minProperties: 1
          additionalProperties: true
          example:
            folders:
            - id: folder_123
              name: Documents
            - id: folder_456
              name: Reports
            fileTypes:
            - pdf
            - docx
            modifiedAfter: '2024-01-01'
    ConnectorToggleRequest:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - sync
          - agent
          description: '''sync'' flips data synchronization; ''agent'' flips use by agents'
        fullSync:
          type: boolean
          description: When turning sync on, start from scratch
          default: false
        deviceId:
          type: string
          minLength: 1
          maxLength: 255
          description: Local FS only
        deviceName:
          type: string
          maxLength: 255
          description: Local FS only
    LocalFsDesktopRefusal:
      type: object
      description: |
        409 body returned when a Local FS connector cannot sync because of its
        owner device.
      required:
      - success
      - code
      - message
      - details
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          enum:
          - DESKTOP_OFFLINE
          - DESKTOP_UNCLAIMED
          - DESKTOP_OWNED_BY_OTHER_DEVICE
        message:
          type: string
          example: No desktop is connected for connector conn_abc123. Open the Pipeshub desktop app on the machine that owns this folder.
        details:
          type: object
          required:
          - code
          - connectorId
          - retryable
          properties:
            code:
              type: string
              enum:
              - DESKTOP_OFFLINE
              - DESKTOP_UNCLAIMED
              - DESKTOP_OWNED_BY_OTHER_DEVICE
            connectorId:
              type: string
            retryable:
              type: boolean
            ownerDeviceName:
              type: string
              description: Name of the owner device, when the connector has one.
    FilterOptions:
      type: object
      description: |
        Option lists for the connector's filters, keyed by filter name, each a list of
        `{value, label}` choices. A connector type lists them only for filters whose
        choices come from the service; none of the current types does, so the object
        is empty. Filter fields themselves come from the connector's registry schema.
      additionalProperties:
        type: array
        items:
          type: object
          properties:
            value:
              type: string
            label:
              type: string
          additionalProperties: true
    OAuthConfig:
      type: object
      description: A saved OAuth app for a connector type. Admins also get `config` (secrets masked when HIDE_SECRET_CONFIG is on) and, in lists, the provider endpoints.
      properties:
        _id:
          type: string
          description: 'OAuth app ID: the `oauthConfigId` to link a connector to'
          format: uuid
        oauthInstanceName:
          type: string
        connectorType:
          type: string
          example: Confluence
        iconPath:
          type: string
          description: Icon of the connector type, copied from the OAuth registry when the configuration was created
          example: /icons/connectors/confluence.svg
        appGroup:
          type: string
          description: Application group of the connector type (empty when the type is not in the OAuth registry)
          example: Atlassian
        appDescription:
          type: string
          description: Description of the connector type's OAuth application
        appCategories:
          type: array
          items:
            type: string
          description: Categories of the connector type
        config:
          type: object
          description: OAuth app credentials; keys follow the connector type's OAuth fields
          additionalProperties: true
          properties:
            clientId:
              type: string
            clientSecret:
              type: string
        userId:
          type: string
        updatedBy:
          type: string
        createdAtTimestamp:
          type: integer
          description: Epoch milliseconds
          format: int64
        updatedAtTimestamp:
          type: integer
          description: Epoch milliseconds
          format: int64
        authorizeUrl:
          type: string
        tokenUrl:
          type: string
        redirectUri:
          type: string
        scopes:
          type: object
          description: Provider scopes requested per use
          additionalProperties:
            type: array
            items:
              type: string
    CreateOAuthConfigRequest:
      type: object
      description: Request to create OAuth configuration (admin only). Stores credentials that users select when setting up connectors.
      required:
      - oauthInstanceName
      - config
      properties:
        oauthInstanceName:
          type: string
          description: Display name for this OAuth configuration (e.g., 'Production Google OAuth'). Must be unique for the connector type within the organization. Leading and trailing whitespace is removed before validation, so a name of only whitespace is refused as empty.
          minLength: 1
          pattern: \S
          example: Production Google OAuth Credentials
        config:
          type: object
          description: |
            OAuth application credentials, keyed by the `name` of each entry in the connector type's
            `authFields` (see `GET /oauth/registry/{connectorType}`), so the keys differ from one
            connector type to the next. Must not be empty; neither the keys nor their values are
            validated when the configuration is created, so a value of another type (a number,
            `null`, a nested object, an array of other items) is stored as sent, also for
            `clientId` and `clientSecret`.
          properties:
            clientId:
              type: string
              description: OAuth client ID from your OAuth application
              example: 123456789-abc.apps.googleusercontent.com
            clientSecret:
              type: string
              description: OAuth client secret; never in the create response, and returned by GET only to admins (masked when HIDE_SECRET_CONFIG is on)
              example: GOCSPX-xxxxxxxxxxxxx
            tenantId:
              type: string
              description: Azure tenant ID (required only for Microsoft connectors)
              example: 12345678-1234-1234-1234-123456789abc
          minProperties: 1
          additionalProperties:
            description: Value of any other auth field the connector type declares, keyed by the field's `name`
            oneOf:
            - type: string
            - type: boolean
            - type: number
            - type: array
              items:
                type: string
        baseUrl:
          type: string
          description: 'PipesHub''s public origin, prefixed to the connector''s redirect path to build the stored redirectUri. When omitted or empty, the frontend public endpoint is used. The value is not checked to be a URL: whatever text is sent is used as the prefix. Not the provider''s URL; a self-hosted provider''s address goes in config.'
          example: https://pipeshub.mycompany.com
    ConnectorPagination:
      type: object
      required:
      - page
      - limit
      - totalCount
      - totalPages
      - hasPrev
      - hasNext
      properties:
        page:
          type: integer
        limit:
          type: integer
        search:
          type: string
          description: The search term the list was filtered by
          nullable: true
        totalCount:
          type: integer
          description: Number of items matching the request across all pages
        totalPages:
          type: integer
          description: Number of pages at the current `limit`
        hasPrev:
          type: boolean
          description: Whether a page exists before this one
        hasNext:
          type: boolean
          description: Whether a page exists after this one
        prevPage:
          type: integer
          nullable: true
          description: Previous page number, `null` on the first page
        nextPage:
          type: integer
          nullable: true
          description: Next page number, `null` on the last page
    ModelType:
      type: string
      enum:
      - llm
      - embedding
      - ocr
      - slm
      - reasoning
      - multiModal
      - imageGeneration
      - tts
      - stt
      - decision
      description: Type of AI model
    WebSearchProviderType:
      type: string
      enum:
      - duckduckgo
      - serper
      - tavily
      - exa
      - brave
      - searxng
      - firecrawl
      - crawl4ai
      description: Supported web search provider. crawl4ai only reads pages (it backs up the built-in page reader) and cannot be the default; firecrawl both searches and reads pages. searxng, firecrawl and crawl4ai take a baseUrl; firecrawl defaults to its cloud API.
    WebSearchProviderItem:
      type: object
      additionalProperties: false
      description: Web search provider configuration item returned by getWebSearchProviders
      required:
      - provider
      - providerKey
      - configuration
      - isDefault
      properties:
        provider:
          $ref: '#/components/schemas/WebSearchProviderType'
        providerKey:
          type: string
          description: Unique key for the provider configuration
        configuration:
          type: object
          description: |
            Provider-specific configuration as stored and returned by the gateway (open record).
            API providers include `apiKey` (masked for non-admins); searxng, firecrawl and crawl4ai
            include `baseUrl` (masked for non-admins too). Additional keys may be present.
          additionalProperties: true
        isDefault:
          type: boolean
    WebSearchSettings:
      type: object
      additionalProperties: false
      description: Normalized web search global settings returned by getWebSearchProviders
      required:
      - includeImages
      properties:
        includeImages:
          type: boolean
          description: Whether to include images in search results
        maxImages:
          type: integer
          minimum: 1
          maximum: 500
          description: Maximum number of images to return when includeImages is true
    WebSearchProvidersResponse:
      type: object
      additionalProperties: false
      description: Response for getWebSearchProviders
      required:
      - status
      - providers
      - settings
      - message
      properties:
        status:
          type: string
          enum:
          - success
        providers:
          type: array
          items:
            $ref: '#/components/schemas/WebSearchProviderItem'
        settings:
          $ref: '#/components/schemas/WebSearchSettings'
        message:
          type: string
          description: Human-readable status (empty list vs populated providers)
    OAuthConfigPagination:
      type: object
      required:
      - page
      - limit
      - totalItems
      - totalPages
      - hasPrev
      - hasNext
      properties:
        page:
          type: integer
        limit:
          type: integer
        search:
          type: string
          nullable: true
        totalItems:
          type: integer
        totalPages:
          type: integer
        hasPrev:
          type: boolean
        hasNext:
          type: boolean
    OAuthRegistryEntry:
      type: object
      description: A connector type that signs in with an OAuth app, with what an admin needs to register that app
      required:
      - name
      - type
      - appGroup
      - authType
      - appDescription
      - appCategories
      - iconPath
      - oauthScopes
      - redirectUri
      - authorizeUrl
      - tokenUrl
      - authFields
      - documentationLinks
      properties:
        name:
          type: string
          example: Jira
        type:
          type: string
          description: The `connectorType` to use in the OAuth app and connector routes
          example: Jira
        appGroup:
          type: string
          example: Atlassian
        authType:
          type: string
          description: Always OAUTH
          example: OAUTH
        appDescription:
          type: string
        appCategories:
          type: array
          items:
            type: string
        iconPath:
          type: string
          example: /icons/connectors/jira.svg
        oauthScopes:
          type: object
          description: Provider scopes requested for each way the connector is used
          required:
          - personalSync
          - teamSync
          - agent
          properties:
            personalSync:
              type: array
              items:
                type: string
            teamSync:
              type: array
              items:
                type: string
            agent:
              type: array
              items:
                type: string
        redirectUri:
          type: string
          description: Path the provider redirects back to; PipesHub's public origin is prefixed to it
          example: connectors/oauth/callback/Jira
        authorizeUrl:
          type: string
        tokenUrl:
          type: string
        additionalParams:
          type: object
          description: Extra query parameters sent on the authorize URL; present for some types only
          additionalProperties:
            type: string
        tokenAccessType:
          type: string
          description: Dropbox and Salesforce only
          example: offline
        authFields:
          type: array
          description: The fields an admin fills in when registering the OAuth app
          items:
            type: object
            required:
            - name
            - displayName
            - placeholder
            - description
            - fieldType
            - required
            - usage
            - defaultValue
            - validation
            - isSecret
            properties:
              name:
                type: string
                example: clientId
              displayName:
                type: string
              placeholder:
                type: string
              description:
                type: string
              fieldType:
                type: string
                enum:
                - TEXT
                - PASSWORD
                - URL
                - SELECT
              required:
                type: boolean
              usage:
                type: string
                enum:
                - CONFIGURE
                - BOTH
              defaultValue:
                type: string
              validation:
                type: object
                properties:
                  minLength:
                    type: integer
                  maxLength:
                    type: integer
              isSecret:
                type: boolean
              options:
                type: array
                description: Present on SELECT fields
                items:
                  type: string
        documentationLinks:
          type: array
          items:
            type: object
            required:
            - title
            - url
            - type
            properties:
              title:
                type: string
              url:
                type: string
              type:
                type: string
                description: For example setup, docs or pipeshub (the casing varies)
    ConnectorFilterValue:
      type: object
      description: A saved filter. Sync parses only entries that carry `operator` and `type`; one without `type` is saved but skipped when the connector syncs.
      required:
      - operator
      - value
      - type
      properties:
        operator:
          type: string
          description: One of the field's `operators`, for example `in` or `is_after`
        value:
          description: The filter value; its type follows `type`
        type:
          type: string
          enum:
          - string
          - boolean
          - datetime
          - list
          - number
          - multiselect
          - select
          description: The field's `filterType` from the registry schema
    ConnectorStoredConfig:
      type: object
      description: A connector instance's saved settings. Secret auth fields come back masked; saving the mask back keeps the stored value. Provider OAuth tokens are never returned.
      properties:
        auth:
          type: object
          description: Auth fields for the instance's auth type, keyed by field name
          additionalProperties: true
          properties:
            authType:
              $ref: '#/components/schemas/ConnectorAuthType'
            connectorType:
              type: string
              description: Set by the server to the instance's connector type
            connectorScope:
              $ref: '#/components/schemas/ConnectorScope'
            oauthConfigId:
              type: string
              description: The shared OAuth app the instance signs in with
            oauthInstanceName:
              type: string
            redirectUri:
              type: string
              description: OAuth redirect URI the server built for this instance
        sync:
          type: object
          description: Sync strategy plus connector-specific sync settings
          additionalProperties: true
          properties:
            selectedStrategy:
              type: string
              description: '`MANUAL`, `SCHEDULED` or `WEBHOOK`'
            scheduledConfig:
              type: object
              additionalProperties: true
              description: Schedule used when `selectedStrategy` is `SCHEDULED`
            customValues:
              type: object
              additionalProperties: true
              description: Values of the connector's own sync fields
        filters:
          type: object
          additionalProperties: true
          description: Saved filter selections
          properties:
            sync:
              type: object
              additionalProperties: true
              description: What to fetch from the source. Selections are under `values`, keyed by filter name.
            indexing:
              type: object
              additionalProperties: true
              description: Which fetched records to index. Selections are under `values`, keyed by filter name.
    ConnectorCreated:
      type: object
      required:
      - connectorId
      - connectorType
      - instanceName
      - scope
      properties:
        connectorId:
          type: string
          description: ID of the new instance
          example: 7b387394-1248-4fb6-810d-e8ac9ac226eb
        connectorType:
          type: string
          description: Connector type the instance was created from
        instanceName:
          type: string
          description: Instance name, trimmed
        created:
          type: boolean
        scope:
          $ref: '#/components/schemas/ConnectorScope'
        createdBy:
          type: string
          description: User ID who created the instance
        isAuthenticated:
          type: boolean
          description: Always `false` on creation
        isConfigured:
          type: boolean
          description: Whether initial configuration was saved with the request
      description: Summary of a connector instance that was just created
    ConnectorSyncCustomField:
      type: object
      description: A connector-specific sync setting. Send its value in `config.sync` under `name`.
      properties:
        name:
          type: string
        displayName:
          type: string
        description:
          type: string
        fieldType:
          type: string
        required:
          type: boolean
        defaultValue: {}
        validation:
          type: object
          additionalProperties: true
        isSecret:
          type: boolean
        nonEditable:
          type: boolean
        options:
          type: array
          items:
            type: string
    ConnectorFilterSection:
      type: object
      properties:
        schema:
          type: object
          properties:
            fields:
              type: array
              items:
                $ref: '#/components/schemas/ConnectorFilterField'
        values:
          type: object
          additionalProperties: true
    ConnectorFilterField:
      type: object
      properties:
        name:
          type: string
          description: 'Filter key: the key in `filters.<sync|indexing>.values`'
        displayName:
          type: string
        description:
          type: string
        filterType:
          type: string
        category:
          type: string
        required:
          type: boolean
        defaultValue: {}
        defaultOperator:
          type: string
          nullable: true
        fallbackOperator:
          type: string
        noImplicitOperatorDefault:
          type: boolean
        operators:
          type: array
          items:
            type: string
        optionSourceType:
          type: string
          enum:
          - manual
          - static
          - dynamic
          description: '`dynamic` options come from GET /connectors/{connectorId}/filters/{filterKey}/options'
        options:
          type: array
          items: {}
    ConnectorAuthSchemaForType:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorAuthField'
        redirectUri:
          type: string
          description: OAuth only. Path appended to the `baseUrl` the connector is created with; the result must be registered as a redirect URI with the provider.
        displayRedirectUri:
          type: boolean
    ConnectorAuthField:
      type: object
      description: One field of an auth form. Send its value in `config.auth` under `name`.
      properties:
        name:
          type: string
        displayName:
          type: string
        placeholder:
          type: string
        description:
          type: string
        fieldType:
          type: string
          description: Input type, for example TEXT, PASSWORD, URL, SELECT, CHECKBOX
        required:
          type: boolean
        usage:
          type: string
        defaultValue:
          description: Default value; its type follows `fieldType`
        validation:
          type: object
          additionalProperties: true
        isSecret:
          type: boolean
          description: Stored values come back masked
        options:
          type: array
          items: {}
        savedOnly:
          type: boolean
          description: 'Shown only on an instance that already has a value saved for it, never on a new one: a way of signing in kept for instances set up with it. Absent means false.'
        requiredUnlessSaved:
          type: string
          description: 'Name of another field: this field is required, except on an instance that has a value saved for that field. Absent means `required` alone applies.'
    ConnectorRegistryEntry:
      type: object
      description: A connector type the org can add.
      properties:
        name:
          type: string
          description: Display name
          example: OneDrive
        type:
          type: string
          description: 'Connector type: the value to pass as `connectorType`'
          example: OneDrive
        appGroup:
          type: string
          description: Product family the connector belongs to
          example: Microsoft 365
        supportedAuthTypes:
          type: array
          description: Authentication methods an instance of this type can be created with
          items:
            $ref: '#/components/schemas/ConnectorAuthType'
        appDescription:
          type: string
          description: One-line description of what the connector syncs
        appCategories:
          type: array
          description: Categories the connector is listed under
          items:
            type: string
          example:
          - Storage
        iconPath:
          type: string
          description: Path of the connector icon
          example: /icons/connectors/onedrive.svg
        supportsRealtime:
          type: boolean
          description: Whether the connector can receive real-time updates
        supportsSync:
          type: boolean
          description: Whether the connector syncs data into the knowledge base
        supportsAgent:
          type: boolean
          description: Whether the connector can be used by AI agents
        documentationLinks:
          type: array
          items:
            $ref: '#/components/schemas/ConnectorDocumentationLink'
        isAdminAccessRequired:
          type: boolean
          description: Whether setting the connector up needs admin rights in the source system
        personalConnectorType:
          type: string
          description: For a team connector type, its personal counterpart, if any
          nullable: true
          example: Notion Personal
        connectorInfo:
          type: string
          description: Guidance shown before setup
          nullable: true
        scope:
          $ref: '#/components/schemas/ConnectorScope'
    ConnectorDocumentationLink:
      type: object
      description: A help link shown on a connector's setup page
      properties:
        title:
          type: string
          description: Link text
          example: Azure AD App Registration Setup
        url:
          type: string
          description: Link target
        type:
          type: string
          description: |
            Free-form link category set by the connector, for example
            `setup`, `pipeshub`, `api` or `docs`.
          example: setup
    MicrosoftCredentials:
      type: object
      additionalProperties: false
      description: |
        Credentials for `microsoft` sign-in. Only `idToken` is read: it is
        verified against Microsoft's signing keys, with the saved client ID as audience.
        Without it the sign-in answers `400`.
      properties:
        idToken:
          type: string
          minLength: 1
          description: Microsoft ID token (JWT)
        accessToken:
          type: string
          description: Accepted but not read
      required:
      - idToken
    GoogleCredentials:
      type: object
      additionalProperties: false
      description: |
        Google ID token wrapped in an object, as Google's sign-in button returns it. Only the
        first token check reads `credential`; the second one (`authenticateWithGoogle`) is
        handed the whole object, so by code reading a sign-in sent this way ends in `500`
        even with a valid token. Send the bare token string instead.
      properties:
        credential:
          type: string
          description: Google ID token (JWT)
      required:
      - credential
    OAuthBearerTokenError:
      type: object
      additionalProperties: false
      description: |
        Error body written by the OAuth bearer-token middleware (RFC 6750 Section 3.1) on routes
        that accept only an OAuth access token, such as `GET /oauth2/userinfo`. The same `error`,
        `error_description` and `scope` values are repeated in the `WWW-Authenticate` response header.
        This is not the standard `ErrorResponse` envelope: `error` is a string.
      properties:
        error:
          type: string
          enum:
          - invalid_request
          - invalid_token
          - insufficient_scope
          - server_error
          description: |
            - `invalid_request` - no `Authorization: Bearer` header was sent
            - `invalid_token` - the token is malformed, expired, revoked, or its user no longer exists
            - `insufficient_scope` - the token is valid but lacks a required scope
            - `server_error` - the scope check itself failed
        error_description:
          type: string
          description: Human-readable explanation of the error
          example: Bearer token required
        scope:
          type: string
          description: Space-separated scopes the route requires. Only present with `insufficient_scope`.
          example: openid
      required:
      - error
      - error_description
    OAuthConfigCredentials:
      type: object
      description: |
        The credentials stored for an OAuth configuration, exactly as the admin submitted them and
        not masked. The keys are the `name` of each entry in the connector type's `authFields`
        (see `GET /oauth/registry/{connectorType}`), so they differ from one connector type to the next.
        Create and update do not check the values, so any JSON value that was sent (a number,
        `null`, a nested object, an array of any items) is stored and returned here as it was sent,
        even for `clientId` and `clientSecret`.
      properties:
        clientId:
          description: OAuth client ID; a string unless something else was sent
          allOf:
          - $ref: '#/components/schemas/OAuthConfigCredentialValue'
        clientSecret:
          description: OAuth client secret, in clear text; a string unless something else was sent
          allOf:
          - $ref: '#/components/schemas/OAuthConfigCredentialValue'
        tenantId:
          description: Directory (tenant) ID, for Microsoft connector types; a string unless something else was sent
          allOf:
          - $ref: '#/components/schemas/OAuthConfigCredentialValue'
      additionalProperties:
        $ref: '#/components/schemas/OAuthConfigCredentialValue'
    OAuthConfigCredentialValue:
      description: |
        A stored credential value, returned exactly as it was sent on create or update. Usually a
        string, boolean, number or list of strings, but the value is not checked, so `null`, a
        nested object or an array of other items comes back as well.
      nullable: true
      anyOf:
      - type: string
      - type: boolean
      - type: number
      - type: array
        items: {}
      - type: object
        additionalProperties: true
    OAuthConfigWithCredentials:
      description: |
        An OAuth configuration as `GET /oauth/{connectorType}/{configId}` returns it. An admin
        gets `config` with the stored credentials; any other caller gets the same object without `config`.
      allOf:
      - $ref: '#/components/schemas/OAuthConfig'
      - type: object
        properties:
          config:
            $ref: '#/components/schemas/OAuthConfigCredentials'
          inherited:
            type: boolean
            description: Present, and `true`, only when the configuration is inherited from another organization rather than owned by the caller's.
    OAuthConfigScopes:
      type: object
      description: OAuth scopes copied from the registry when the configuration was created, by use case
      properties:
        personal_sync:
          type: array
          items:
            type: string
          description: Scopes requested for a personal connector
        team_sync:
          type: array
          items:
            type: string
          description: Scopes requested for a team connector
        agent:
          type: array
          items:
            type: string
          description: Scopes requested for agent tools
    OAuthConfigRecord:
      description: |
        An OAuth configuration as `GET /oauth/{connectorType}` lists it. An admin gets the stored
        record in full, credentials included. Any other caller gets only the `OAuthConfig` fields.
        The provider fields (`authorizeUrl`, `tokenUrl`, `redirectUri`, `scopes` and the optional ones
        after them) are copied from the OAuth registry when the configuration is created, so a
        configuration created under a type that is not in the registry has none of them.
      allOf:
      - $ref: '#/components/schemas/OAuthConfig'
      - type: object
        properties:
          userId:
            type: string
            description: ID of the admin who created the configuration (admins only)
          orgId:
            type: string
            description: Organization that owns the configuration (admins only)
          createdBy:
            type: string
            description: ID of the admin who created the configuration (admins only)
          updatedBy:
            type: string
            description: ID of the admin who last updated the configuration (admins only)
          config:
            $ref: '#/components/schemas/OAuthConfigCredentials'
          authorizeUrl:
            type: string
            description: Provider authorization URL, from `config.authorizeUrl` when the admin supplied one and from the registry otherwise (admins only)
          tokenUrl:
            type: string
            description: Provider token URL, from `config.tokenUrl` when the admin supplied one and from the registry otherwise (admins only)
          redirectUri:
            type: string
            description: Redirect URI to register with the provider, built from `baseUrl` (or the frontend public endpoint) and the registry's redirect path. Empty when the registry has no redirect path. (admins only)
            example: http://localhost:3001/connectors/oauth/callback/Confluence
          scopes:
            $ref: '#/components/schemas/OAuthConfigScopes'
          tokenAccessType:
            type: string
            description: Token access type sent to the provider. Present only when the registry sets one. (admins only)
            example: offline
          additionalParams:
            $ref: '#/components/schemas/OAuthAuthorizeParams'
          scopeParameterName:
            type: string
            description: Name of the authorization-URL parameter that carries the scopes. Present only when it is not `scope`. (admins only)
            example: user_scope
          tokenResponsePath:
            type: string
            description: Key under which the provider nests the token in its token response. Present only when the registry sets one. (admins only)
            example: authed_user
    OAuthAuthorizeParams:
      type: object
      description: Extra query parameters added to the provider authorization URL. The keys are provider-specific.
      additionalProperties:
        type: string
      example:
        access_type: offline
        prompt: consent
    OAuthRegistryPagination:
      type: object
      description: Pagination block of `GET /oauth/registry` and `GET /oauth/{connectorType}`
      properties:
        page:
          type: integer
          description: Current page number
        limit:
          type: integer
          description: Items per page
        search:
          type: string
          nullable: true
          description: The search term that was applied, or null
        totalCount:
          type: integer
          description: Number of items that match
        totalPages:
          type: integer
        hasPrev:
          type: boolean
        hasNext:
          type: boolean
        prevPage:
          type: integer
          nullable: true
          description: Previous page number, or null on the first page
        nextPage:
          type: integer
          nullable: true
          description: Next page number, or null on the last page
    UpdateRecordResponseSchema:
      type: object
      additionalProperties: false
      description: Response returned by PUT /knowledgeBase/record/{recordId}.
      required:
      - message
      - record
      - fileUploaded
      - meta
      properties:
        message:
          type: string
          description: |
            `Record updated successfully` for a rename, `Record updated with new file version`
            when a replacement file was sent.
        record:
          description: The record's graph document as stored after the update.
          allOf:
          - $ref: '#/components/schemas/GraphRecordFields'
          - type: object
            properties:
              id:
                type: string
                description: Record ID.
              _key:
                type: string
                description: The record ID again. Present when the graph database is Neo4j.
              _id:
                type: string
                x-speakeasy-name-override: graphDocumentId
                description: |
                  The record's graph document handle, `records/<id>`. Not the record ID: use `id`.
                  Named `graphDocumentId` in the SDKs, where `id` is the record ID.
              _rev:
                type: string
                description: Revision of the graph document. Present when the graph database is ArangoDB.
              isPlaceholder:
                type: boolean
                nullable: true
                description: True while the record is a stub whose content has not been synced yet.
              deletedAtTimestamp:
                type: integer
                format: int64
                description: When the record was moved to the trash. Present only on a record that is in the trash.
              deleteBatchId:
                type: string
                description: The delete batch the record belongs to. Present only on a record that is in the trash.
              deleteSource:
                type: string
                description: Who moved the record to the trash (`USER` for a delete through the API). Present only on a record that is in the trash.
                example: USER
              restoredAtTimestamp:
                type: integer
                format: int64
                description: When the record was last brought back from the trash. Absent if it never was.
        fileUploaded:
          type: boolean
          description: Whether the request carried a replacement file.
        meta:
          type: object
          additionalProperties: false
          required:
          - timestamp
          properties:
            requestId:
              type: string
              description: Identifier of this request.
            timestamp:
              type: string
              format: date-time
              description: When the response was generated.
    AgentAddMessageResponse:
      type: object
      additionalProperties: false
      description: |
        Envelope returned by
        `POST /agents/{agentKey}/conversations/{conversationId}/messages`:
        the updated agent conversation, the number of citation records used
        to ground the answer for this turn, and request metadata.
      required:
      - conversation
      - recordsUsed
      - meta
      properties:
        conversation:
          $ref: '#/components/schemas/AgentConversation'
        recordsUsed:
          type: integer
          minimum: 0
          description: Number of citation records used to ground the answer generated for this turn.
        meta:
          type: object
          additionalProperties: false
          required:
          - timestamp
          - duration
          - recordsUsed
          properties:
            requestId:
              type: string
              description: Request correlation id. Omitted when no request id was set on the context.
            timestamp:
              type: string
              format: date-time
              description: Server timestamp when the response was sent.
            duration:
              type: integer
              minimum: 0
              description: Total handler duration in milliseconds.
            recordsUsed:
              type: integer
              minimum: 0
              description: Same value as the top-level `recordsUsed`.
    NavigateDateQuery:
      type: string
      description: |
        A date filter of `GET /connectors/navigate`: `YYYY-MM-DD` (UTC; start of
        the day for a lower bound, end of the day for an upper bound), or a date
        and time with a timezone offset (`Z` or `±HH:MM`). Empty, blank or
        timezone-naive values are refused with `400`.
      pattern: ^\d{4}-\d{2}-\d{2}([T ]\d{2}(:\d{2}(:\d{2}([.,]\d+)?)?)?([Zz]|[+-]\d{2}(:?\d{2})?))?$
      example: '2026-01-15T08:00:00Z'
    AgentMcpServerRef:
      type: object
      additionalProperties: false
      description: |
        One MCP server instance attached to an agent: a reference only, no secrets.
      required:
      - instanceId
      - name
      properties:
        instanceId:
          type: string
          minLength: 1
          maxLength: 256
          pattern: \S
          description: MCP server instance id. Surrounding whitespace is trimmed.
        name:
          type: string
          minLength: 1
          maxLength: 200
          pattern: \S
          description: Server name. Surrounding whitespace is trimmed.
        displayName:
          type: string
          maxLength: 200
        typeId:
          type: string
          maxLength: 200
          description: Server type; at most one attached instance per type.
        allTools:
          type: boolean
          description: |
            Attach every tool the server offers at chat time, including ones it adds later.
            Without it, `tools` must name at least one tool, or the request is refused with
            `400` ("Choose at least one tool for MCP server(s) ..., or attach all of their tools.").
        tools:
          type: array
          maxItems: 5000
          description: |
            Stored tool selection for this server. At most 500 tools of one server are kept:
            more are refused with `400`, unless `allTools` is set, when the first 500 are kept.
          items:
            $ref: '#/components/schemas/AgentCreateToolRef'
  responses:
    XssRejected:
      description: 'Refused before authentication because a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BodyParserFailure:
      description: 'An unexpected failure on PipesHub''s side (`INTERNAL_ERROR`). A body the app-wide parsers refuse is not answered here: malformed JSON is a `400`, a body past the size limits a `413` and an unsupported encoding a `415` (see Body parsers in the introduction).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
security:
- bearerAuth: []
- oauth2: []
paths:
  /oauth2/token:
    post:
      tags:
      - OAuth Provider
      summary: Exchange authorization code for tokens
      description: |
        OAuth 2.0 Token Endpoint (RFC 6749 Section 4.1.3).

        Exchanges an authorization code, client credentials, refresh token, device code or
        service token for access tokens.
        Successful responses carry `Cache-Control: no-store` and `Pragma: no-cache`.

        **Grant Types:**
        - `authorization_code`: Exchange auth code for tokens (user-based)
        - `client_credentials`: Get tokens for machine-to-machine auth
        - `urn:ietf:params:oauth:grant-type:device_code`: Poll for the tokens of a device authorization
          (RFC 8628); answered `400` with `authorization_pending` until the user approves
        - `refresh_token`: Get new access token using refresh token. The refresh token must have been issued to the presenting `client_id`; one issued to another client is rejected with `400 invalid_grant` and is left untouched (not rotated, not revoked).
        - `urn:ietf:params:oauth:grant-type:token-exchange`: Service-account
          delegation (RFC 8693). A service account exchanges its own token for
          a five-minute token that acts as one named person from its
          allow-list. **Enterprise edition.** The Community build answers this
          grant with `unsupported_grant_type` and leaves it out of discovery,
          so check `grant_types_supported` rather than assuming it is there. **This grant sends no `client_id` or `client_secret`** —
          the `subject_token` is the authentication, since it already carries
          a verified identity and the scopes that bound it. Refusals about the
          person asked for all return `400 invalid_target` with one wording;
          the cause is recorded in the delegation log, which only an
          administrator can read.

        For **`client_credentials`**, access tokens represent the **service account the app is pointed at** (`tokenIdentityUserId`), or the **OAuth app creator** for an app registered before that was required and never bound. The JWT may encode **`userId === client_id`**; the **Node API gateway** loads the application record on every request and resolves the identity from it, treating the **`createdBy`** claim as a cross-check and refusing a token whose claim no longer matches it — see **OAuth Provider** tag.

        **Client Authentication:**
        Can be provided via:
        - HTTP Basic auth: `Authorization: Basic base64(client_id:client_secret)`
        - Request body: `client_id` and `client_secret` parameters

        **PKCE Verification:**
        If authorization used PKCE, the `code_verifier` must be provided and will be
        verified against the stored code challenge.
      operationId: oauthToken
      security: []
      requestBody:
        description: Request payload
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OAuthTokenRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthTokenRequest'
        required: true
      responses:
        '200':
          description: Tokens issued successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthTokenResponse'
              example:
                access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                token_type: Bearer
                expires_in: 3600
                refresh_token: dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...
                scope: openid profile email offline_access
        '400':
          description: |
            The grant is refused with the flat OAuth body `{ error, error_description }`:
            - `invalid_request` - the body fails validation (`unsupported_grant_type` instead when
              `grant_type` is a non-empty string the schema does not accept)
            - `invalid_grant` - `code`, `redirect_uri`, `refresh_token` or `device_code` missing,
              or an unknown, expired or already used authorization code. Also an authorization code
              or approved device code whose `knowledgeLimit` the app's current limit no longer
              contains, because the app's limit was narrowed after it was issued ("The
              application's permissions changed after you allowed it. Sign in again."). A widened
              limit does not refuse it; the token carries the limit the user agreed to. Also a
              `refresh_token` that another refresh presenting it at the same time rotated first
              ("Refresh token has already been used"); only one of them gets a new pair.
            - `unsupported_grant_type` - the app does not have the grant
            - `invalid_scope` - a requested scope is not allowed for the app, or the token would carry
              no scope at all ("A token must carry at least one scope"). A `client_credentials` grant
              drops `openid`, `profile`, `email` and `offline_access`, so it needs at least one other
              scope, requested or allowed for the app.
            - `authorization_pending`, `slow_down`, `expired_token`, `access_denied` - device_code
              polling (RFC 8628 Section 3.5): still pending, polled sooner than `interval`, unknown,
              expired or already redeemed, or denied by the user. `access_denied` is a `400` here,
              not a `403`.
            - `invalid_target`, `invalid_request`, `invalid_grant`, `invalid_scope`,
              `unsupported_grant_type` - a refusal from the token-exchange grant (see above)
            - `server_error` - any other failure, also with status `400`. This includes an unknown or
              revoked `refresh_token` ("Invalid refresh token") and a `client_credentials` request
              without `client_secret`, whose `error_description` is the Node `TypeError` text
              (`The "data" argument must be of type string ... Received undefined`). A
              `client_credentials` grant whose identity is gone, disabled or being restored is also
              refused this way ("The identity this application acts as no longer exists", "... is
              disabled", "... is being restored. Try again once that has finished.").

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ErrorResponse'
                - $ref: '#/components/schemas/OAuthErrorResponse'
        '401':
          description: |
            Client authentication failed (`invalid_client`): no `client_id` in the body or the Basic
            header, an unknown or inactive client, a wrong `client_secret`, or a confidential client
            using `authorization_code`, `refresh_token` or `device_code` without `client_secret`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '500':
          $ref: '#/components/responses/BodyParserFailure'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /oauth2/revoke:
    post:
      tags:
      - OAuth Provider
      summary: Revoke an access or refresh token
      description: |
        OAuth 2.0 Token Revocation Endpoint (RFC 7009).

        Revokes an access token or refresh token, preventing further use.
        Revoking a refresh token also invalidates associated access tokens.

        **Use Cases:**
        - User logs out of third-party app
        - User revokes app access from account settings
        - Security incident response

        **Note:** Returns 200 OK even if token was already revoked or invalid
        (per RFC 7009, to prevent token enumeration).
      operationId: oauthRevoke
      security: []
      requestBody:
        description: Request payload
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OAuthRevokeRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthRevokeRequest'
        required: true
      responses:
        '200':
          description: |
            Token revoked, or it was unknown, already revoked or issued to another client. No body.
        '400':
          description: |
            The body fails validation (`VALIDATION_ERROR`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/BodyParserFailure'
        '401':
          description: |
            Client authentication failed (`invalid_client`): an unknown or inactive `client_id`
            (`Invalid client_id`), a confidential client without `client_secret` (`client_secret required
            for confidential clients`), or a wrong `client_secret`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /oauth2/introspect:
    post:
      tags:
      - OAuth Provider
      summary: Introspect a token
      description: |
        OAuth 2.0 Token Introspection Endpoint (RFC 7662).

        Check if a token is active and retrieve its metadata.

        **Use Cases:**
        - Resource servers validating tokens
        - Debugging token issues
        - Checking token scopes before processing requests

        **Response:**
        - Active token: Returns `active: true` with token metadata
        - Invalid/expired/revoked token: Returns only `active: false`
      operationId: oauthIntrospect
      security: []
      requestBody:
        description: Request payload
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OAuthIntrospectRequest'
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthIntrospectRequest'
        required: true
      responses:
        '200':
          description: |
            Token introspection result. `{active: false}` alone when the token is unknown, expired,
            revoked, issued to another client, or when `client_secret` is missing (even for a live
            token). `username` is present only for a token that acts as a user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthIntrospectResponse'
              examples:
                active:
                  summary: Active token
                  value:
                    active: true
                    scope: openid profile email
                    client_id: abc123
                    username: user@example.com
                    token_type: Bearer
                    exp: 1735686000
                    iat: 1735682400
                    user_id: user-id-123
                    iss: https://api.pipeshub.com
                inactive:
                  summary: Inactive/invalid token
                  value:
                    active: false
        '400':
          description: |
            The body fails validation (`VALIDATION_ERROR`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Client authentication failed (`invalid_client`) - unknown or inactive client, or wrong `client_secret`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthErrorResponse'
        '500':
          $ref: '#/components/responses/BodyParserFailure'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /oauth2/userinfo:
    get:
      tags:
      - OpenID Connect
      summary: Get authenticated user information
      description: |
        OpenID Connect UserInfo Endpoint.

        Returns claims about the authenticated user. Requires a valid access token
        with the `openid` scope.

        **Available Claims:**
        - `user_id` - User identifier
        - `name`, `given_name`, `family_name` - Name claims (with `profile` scope)
        - `email`, `email_verified` - Email claims (with `email` scope)

        **Authentication:**
        Pass the access token as a Bearer token: `Authorization: Bearer {access_token}`

        The route takes no parameters; query parameters are ignored.
      operationId: oauthUserInfo
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthUserInfoResponse'
              example:
                user_id: user-id-123
                name: John Doe
                given_name: John
                family_name: Doe
                email: john.doe@example.com
                email_verified: true
        '400':
          $ref: '#/components/responses/XssRejected'
        '401':
          description: |
            Missing, malformed, expired or revoked access token, or the token's user no longer
            exists. `error` is `invalid_request` when no bearer token was sent and `invalid_token`
            otherwise.

            A delegated token (Enterprise: a service account acting as a person) is also refused
            with `invalid_token` once the delegation no longer holds, and `error_description` says
            why: the person was deleted ("This token acts for someone who no longer exists"), is
            disabled ("This account is disabled"), is now an administrator ("This token acts for
            someone who is now an administrator") or is a service account ("This token acts for a
            service account"); the service account is deleted or disabled ("The service account
            behind this token is no longer active"); or its allow-list entry was removed ("This
            service account may no longer act as this person").
          headers:
            WWW-Authenticate:
              description: RFC 6750 challenge repeating the error, e.g. `Bearer realm="oauth", error="invalid_token", error_description="Invalid access token"`
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthBearerTokenError'
              example:
                error: invalid_request
                error_description: Bearer token required
        '403':
          description: Token does not have openid scope
          headers:
            WWW-Authenticate:
              description: RFC 6750 challenge repeating the error and the required scope
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthBearerTokenError'
              example:
                error: insufficient_scope
                error_description: 'Required scopes: openid'
                scope: openid
        '500':
          description: |
            The scope check failed unexpectedly (OAuth body, `error` is `server_error`).

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/OAuthBearerTokenError'
                - $ref: '#/components/schemas/ErrorResponse'
  /oauth-clients:
    get:
      tags:
      - OAuth Apps
      summary: List OAuth apps
      description: |
        Returns a paginated list of OAuth apps registered by the signed-in user. Access is creator-scoped — even org admins only see apps they created themselves, so this endpoint is safe to use for per-user developer dashboards without leaking org-wide app metadata.

        Each entry carries the full app configuration except the client secret, which is only ever returned at creation time and immediately after a regeneration.

        Use the `status` query parameter to filter by lifecycle state (`active`, `suspended`, `revoked`) and `search` for a case-insensitive substring match against `name` or `description`.
      operationId: listOAuthApps
      security:
      - bearerAuth: []
      parameters:
      - name: page
        in: query
        allowEmptyValue: true
        schema:
          type: integer
          minimum: 1
          default: 1
        description: |
          Page number (matches `listAppsQuerySchema`: defaults to `1` when omitted or empty).
      - name: limit
        in: query
        allowEmptyValue: true
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        description: |
          Items per page (defaults to `20` when omitted or empty; max 100).
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - suspended
          - revoked
        description: Filter by status. `revoked` always yields an empty page, because an app only becomes revoked by being deleted and deleted apps are never listed.
      - name: search
        in: query
        schema:
          type: string
        description: Search by app name or description (case-insensitive)
      responses:
        '200':
          description: List of OAuth apps
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthAppListResponse'
        '400':
          description: |
            Bad request — the request failed validation

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
    post:
      tags:
      - OAuth Apps
      summary: Create OAuth app
      description: |
        Register a new OAuth app for the organization. Any authenticated org member may create apps; the creator is recorded as the app's owner and is the only user who can subsequently read, update, suspend, activate, regenerate the secret of, or delete it.

        The `clientSecret` is returned in this response **only** — it is stored hashed server-side and cannot be retrieved later. Persist it before exiting the create flow; if it is ever lost, rotate via `POST /oauth-clients/{appId}/regenerate-secret`.

        `allowedScopes` is validated against the caller's role-aware scope set (see `GET /oauth-clients/scopes`). Org admins may include admin-only scopes; non-admins requesting a restricted scope receive `400`.

        All `/oauth-clients/*` routes share a per-user rate limiter (default 1000 req/min, configurable via the `MAX_OAUTH_CLIENT_REQUESTS_PER_MINUTE` env var).
      operationId: createOAuthApp
      security:
      - bearerAuth: []
      requestBody:
        description: Request body for Create OAuth app
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOAuthAppRequest'
        required: true
      responses:
        '201':
          description: OAuth app created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOAuthAppResponse'
        '400':
          description: |
            Invalid request (validation error), including a `knowledgeLimit` with a key other than `apps`, `recordGroups` and `records`, an id that
            is not a UUID, or no id at all or more than 50 once duplicates are dropped.

            `allowedGrantTypes` holds `client_credentials` and `tokenIdentityUserId` is missing
            (`HTTP_BAD_REQUEST`, `An application that uses client_credentials must name the service account
            its tokens act as. ...`), or names a disabled service account (`That service account is
            disabled. Enable it before pointing an application at it.`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account, or the application allows client_credentials and the caller is not an organisation administrator
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '404':
          description: The selected tokenIdentityUserId is malformed, or does not name a service account in this organisation. A disabled account answers 400 instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /oauth-clients/scopes:
    get:
      tags:
      - OAuth Apps
      summary: List available scopes
      description: |
        Returns the OAuth scopes the signed-in user is permitted to register on new or updated apps, grouped by category. Use this to populate scope-picker UIs and to validate `allowedScopes` client-side before submitting to `createOAuthApp` / `updateOAuthApp`.

        The result is role-aware. Org admins (members of an admin user group) receive every registered scope; everyone else is filtered to exclude admin-only scopes: `org:write`, `org:admin`, `user:invite`, `user:delete`, `usergroup:write`, `team:write`, `config:write`, `crawl:write`, `crawl:delete`.

        Each key in the `scopes` map matches the `category` field on the `OAuthScopeInfo` entries it contains. A category may appear with an empty array when every scope it contains is restricted for the caller — treat empty buckets as "no permitted scopes in this group", not as a missing category.

        Shares the per-user rate limiter applied to every `/oauth-clients/*` route (default 1000 req/min, `MAX_OAUTH_CLIENT_REQUESTS_PER_MINUTE`).
      operationId: listOAuthScopes
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List of available scopes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthScopesGroupedResponse'
              example:
                scopes:
                  Identity:
                  - name: openid
                    description: OpenID Connect authentication
                    category: Identity
                    requiresUserConsent: false
                  - name: profile
                    description: User profile information (name, picture)
                    category: Identity
                    requiresUserConsent: true
                  Knowledge Base:
                  - name: kb:read
                    description: Read knowledge bases and records
                    category: Knowledge Base
                    requiresUserConsent: true
        '400':
          $ref: '#/components/responses/XssRejected'
        '401':
          description: Unauthorized — missing/invalid token, or session invalidated (e.g. password change after token issuance)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded for OAuth client management routes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
              example:
                error:
                  code: TOO_MANY_REQUESTS
                  message: Too many OAuth client requests. Please try again later.
                  retryAfter: 45
  /oauth-clients/{appId}:
    get:
      tags:
      - OAuth Apps
      summary: Get OAuth app details
      description: |
        Returns the full configuration of an OAuth app you registered. The `clientSecret` is never echoed back here; if you need a new one, call `POST /oauth-clients/{appId}/regenerate-secret`.

        Access is creator-scoped: even org admins receive `404` for apps owned by other users. This avoids leaking app metadata across org members and keeps the read surface symmetric with `listOAuthApps`.
      operationId: getOAuthApp
      security:
      - bearerAuth: []
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
        description: OAuth app ID (MongoDB ObjectId)
      responses:
        '200':
          description: OAuth app details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthAppResponse'
        '400':
          description: |
            `appId` is not a 24-character hex id (`VALIDATION_ERROR` naming `params.appId`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account. An app the caller did not create is 404, not 403.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '404':
          description: OAuth app not found or not visible to this caller (each user only sees apps they created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
    put:
      tags:
      - OAuth Apps
      summary: Update OAuth app
      description: |
        Update an OAuth app's configuration. All body fields are optional — supply only what should change. URL fields (`homepageUrl`, `privacyPolicyUrl`, `termsOfServiceUrl`) accept `null` to clear them.

        **Adding `client_credentials`** to `allowedGrantTypes` requires an organisation administrator, because
        it settles whose documents the application's tokens reach. A non-administrator answers `403`, and that
        check runs first — so a member sees `403` whether or not a service account is bound.

        For an administrator, it answers `400` when no service account is bound or the bound account is
        disabled, and `404` when the bound identity no longer exists or is not a service account — distinct
        from the `404` for an application this caller cannot see. Point the application at one first with
        `PUT /oauth-clients/{appId}/token-identity`. An application that already allows the grant without a
        service account predates this rule and can still be edited.

        Creator-only: even org admins cannot edit apps owned by other users.

        When modifying `allowedScopes`, the new set must remain a subset of the caller's role-aware scope list (same rule as `GET /oauth-clients/scopes`). The Zod refine on `updateAppSchema` only looks at the body: it refuses `allowedGrantTypes` containing `authorization_code` together with an empty `redirectUris` (`400 VALIDATION_ERROR`), but sending `authorization_code` without `redirectUris` is accepted even when the stored app has no redirect URI.

        This endpoint never rotates the client secret — use `POST /oauth-clients/{appId}/regenerate-secret` for that.
      operationId: updateOAuthApp
      security:
      - bearerAuth: []
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
        description: OAuth app ID
      requestBody:
        description: Fields to change. A request with no body, or `{}`, is accepted and changes nothing (`200` with the app).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOAuthAppRequest'
        required: false
      responses:
        '200':
          description: OAuth app updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateOAuthAppResponse'
        '400':
          description: |
            Validation error, including a `knowledgeLimit` with a key other than `apps`, `recordGroups` and `records`, an id that
            is not a UUID, or no id at all or more than 50 once duplicates are dropped. `null` is accepted and lifts the limit.

            The update adds `client_credentials` and the application is not bound to a service account
            (`HTTP_BAD_REQUEST`, `Point this application at a service account before allowing
            client_credentials. ...`), or the bound one is disabled (`That service account is disabled.
            Enable it before pointing an application at it.`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account, or the update adds `client_credentials` and the caller is not an organisation administrator. An app the caller did not create is 404, not 403.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '404':
          description: OAuth app not found or not visible to this caller (each user only sees apps they created), or the service account the application is bound to no longer exists or is not a service account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '409':
          description: The request changes `knowledgeLimit`, and the app's limit changed after this request read it (another edit saved first). Nothing was saved. Reload the app and save again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
    delete:
      tags:
      - OAuth Apps
      summary: Delete OAuth app
      description: |
        Soft-deletes an OAuth app. The app is flagged `isDeleted=true` on the `OAuthApp` document, removed from list/get responses for every caller, and all of its access and refresh tokens are revoked in the same operation. There is no restore endpoint — deletion is final.

        Creator-only: even org admins cannot delete apps owned by other users.
      operationId: deleteOAuthApp
      security:
      - bearerAuth: []
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
        description: OAuth app ID
      responses:
        '200':
          description: OAuth app deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: OAuth app deleted successfully
        '400':
          description: |
            `appId` is not a 24-character hex id (`VALIDATION_ERROR` naming `params.appId`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account. An app the caller did not create is 404, not 403.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '404':
          description: OAuth app not found or not visible to this caller (each user only sees apps they created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /oauth-clients/{appId}/regenerate-secret:
    post:
      tags:
      - OAuth Apps
      summary: Regenerate client secret
      description: |
        Generates a fresh client secret for an OAuth app. The previous secret is invalidated immediately — any client still presenting it will fail token exchange at `POST /oauth2/token` until updated.

        The new secret is returned in this response **only** and cannot be retrieved later. Pair this call with credential propagation to every integration that uses the app. If the rotation was triggered by a suspected leak, also call `POST /oauth-clients/{appId}/revoke-all-tokens` to invalidate already-issued access and refresh tokens instead of waiting for their natural expiry.

        Creator-only: even org admins cannot rotate secrets for other users' apps.
      operationId: regenerateOAuthAppSecret
      security:
      - bearerAuth: []
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
        description: OAuth app ID
      responses:
        '200':
          description: New client secret generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegenerateOAuthAppSecretResponse'
        '400':
          description: |
            `appId` is not a 24-character hex id (`VALIDATION_ERROR` naming `params.appId`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account. An app the caller did not create is 404, not 403.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '404':
          description: OAuth app not found or not visible to this caller (each user only sees apps they created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /oauth-clients/{appId}/suspend:
    post:
      tags:
      - OAuth Apps
      summary: Suspend OAuth app
      description: |
        Moves an OAuth app to `status: "suspended"`, blocking new token issuance at `POST /oauth2/token` and the authorization-code consent flow. Tokens that have already been issued remain valid until their natural expiry — call `POST /oauth-clients/{appId}/revoke-all-tokens` immediately afterwards if you need an immediate lockout.

        Use this for temporary suspensions where you intend to reactivate later. For permanent removal, use `DELETE /oauth-clients/{appId}`. Suspending an app that is already suspended returns `400`.

        Creator-only.
      operationId: suspendOAuthApp
      security:
      - bearerAuth: []
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
        description: OAuth app ID
      responses:
        '200':
          description: OAuth app suspended
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuspendOAuthAppResponse'
        '400':
          description: |
            The app is already suspended, or `appId` is not a 24-character hex id (`VALIDATION_ERROR` naming `params.appId`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account. An app the caller did not create is 404, not 403.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '404':
          description: OAuth app not found or not visible to this caller (each user only sees apps they created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /oauth-clients/{appId}/activate:
    post:
      tags:
      - OAuth Apps
      summary: Activate suspended OAuth app
      description: |
        Moves a suspended OAuth app back to `status: "active"`, restoring its ability to authenticate and obtain new tokens via `POST /oauth2/token`.

        Activating an app that is already active returns `400`. A deleted app (the only way an app becomes `revoked`) is hidden from every lookup, so activating it returns `404`, not the service's "Cannot activate a revoked app" `400`; the only path back is to register a new app.

        Creator-only.
      operationId: activateOAuthApp
      security:
      - bearerAuth: []
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
        description: OAuth app ID
      responses:
        '200':
          description: OAuth app activated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivateOAuthAppResponse'
        '400':
          description: |
            The app is already active, or `appId` is not a 24-character hex id (`VALIDATION_ERROR` naming `params.appId`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account. An app the caller did not create is 404, not 403.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '404':
          description: OAuth app not found or not visible to this caller (each user only sees apps they created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /oauth-clients/{appId}/tokens:
    get:
      tags:
      - OAuth Apps
      summary: List app tokens
      description: |
        Lists active access and refresh tokens currently issued to an OAuth app, sorted newest first. Useful for auditing app usage and picking specific tokens to investigate before a targeted revocation.

        Each entry includes the token type (`access` or `refresh`), the user the token was issued for (omitted for client-credentials access tokens), the granted scopes, the issuance and expiry timestamps, and the revocation flag. Each type is capped at 100 most-recent rows server-side (`listTokensForApp` in `oauth_token.service.ts`); revoked and expired tokens are excluded.

        Creator-only.
      operationId: listOAuthAppTokens
      security:
      - bearerAuth: []
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
        description: OAuth app ID
      responses:
        '200':
          description: List of tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthAppTokensListResponse'
        '400':
          description: |
            `appId` is not a 24-character hex id (`VALIDATION_ERROR` naming `params.appId`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account. An app the caller did not create is 404, not 403.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '404':
          description: OAuth app not found or not visible to this caller (each user only sees apps they created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /oauth-clients/{appId}/revoke-all-tokens:
    post:
      tags:
      - OAuth Apps
      summary: Revoke all app tokens
      description: |
        Revokes every access and refresh token currently issued to an OAuth app, in a single operation. Use this for emergency credential rotation, suspected secret leaks, or as a follow-up to `POST /oauth-clients/{appId}/regenerate-secret` when you want existing sessions invalidated immediately rather than letting them expire naturally.

        The response carries only a confirmation `message`; it does not say how many tokens were revoked. Clients of this app must then obtain new tokens via the standard OAuth flow.

        Creator-only.
      operationId: revokeAllOAuthAppTokens
      security:
      - bearerAuth: []
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
        description: OAuth app ID
      responses:
        '200':
          description: All tokens revoked
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
                    example: All tokens revoked successfully
        '400':
          description: |
            `appId` is not a 24-character hex id (`VALIDATION_ERROR` naming `params.appId`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: Bearer token is an OAuth access token or personal access token rather than a user session, or the caller is a service account. An app the caller did not create is 404, not 403.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '404':
          description: OAuth app not found or not visible to this caller (each user only sees apps they created)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /personal-access-tokens:
    get:
      tags:
      - Personal Access Tokens
      summary: List your own personal access tokens
      description: |
        Lists the caller's own active (non-revoked, unexpired) personal
        access tokens, newest first, capped at 100 rows server-side. Never
        returns another user's tokens — see `GET /personal-access-tokens/admin`
        for the org-admin, cross-user view. The handler reads no query parameters
        and ignores any that are sent.

        Shares the same per-user rate limiter as `/oauth-clients/*`
        (default 1000 req/min, `MAX_OAUTH_CLIENT_REQUESTS_PER_MINUTE`).
      operationId: listPersonalAccessTokens
      security:
      - bearerAuth: []
      responses:
        '200':
          description: The caller's active personal access tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPatResponse'
        '400':
          $ref: '#/components/responses/XssRejected'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: The bearer token is an OAuth access token or a personal access token rather than an interactive user session, or the caller is a service account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
    post:
      tags:
      - Personal Access Tokens
      summary: Create a personal access token
      description: |
        Mints a new personal access token for the caller. Deliberately not
        admin-gated — any authenticated org member may create their own,
        unlike OAuth app registration.

        The token is minted against a lazily-created, per-org synthetic
        OAuth app (`clientId: pat-system:<orgId>`) shared by every PAT in
        that org — the same signing, hashing, and revocation machinery as
        `/oauth2/token`, reused rather than duplicated.

        `scopes` is validated against the org's configured `MCP_SCOPES`
        env var, not the full role-aware OAuth-app scope catalog — a
        non-admin can request any scope in that set.

        **Session only.** The bearer token must be the user's interactive
        session JWT. OAuth access tokens and personal access tokens
        (`phpat_...`) are rejected with `403`, so a token that is already
        issued cannot mint another with wider scopes or a longer life.

        The response's `accessToken` is shown **once**; only its SHA-256
        hash is stored. It's prefixed `phpat_` (see the `bearerAuth`
        security scheme).
      operationId: createPersonalAccessToken
      security:
      - bearerAuth: []
      requestBody:
        description: Request body for Create personal access token
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePatRequest'
        required: true
      responses:
        '201':
          description: Personal access token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePatResponse'
        '400':
          description: |
            Invalid request: a `VALIDATION_ERROR` from the body validator (missing,
            empty or over-long `name`, `scopes` not a non-empty list, `expiryDays`
            other than 30, 90, 365 or "never", a `knowledgeLimit` with a key other than `apps`, `recordGroups` and `records`, an id that is not a UUID, or no id at all or more than 50 once duplicates are dropped), or a requested scope that isn't in
            the org's configured `MCP_SCOPES` (refused by the service, code
            `OAUTH_INVALID_SCOPE`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: The bearer token is an OAuth access token, a personal access token (`phpat_`) or a service token (`phsvc_`) rather than an interactive user session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /personal-access-tokens/scopes:
    get:
      tags:
      - Personal Access Tokens
      summary: List scopes available for a new personal access token
      description: |
        Returns the org's configured `MCP_SCOPES` as a flat array of scope
        definitions, for populating the create-token scope picker. Unlike
        `GET /oauth-clients/scopes`, this is **not** grouped by category and
        **not** role-aware — every org member sees the same set, since PAT
        scope selection isn't gated by admin status. The handler reads no query
        parameters and ignores any that are sent.
      operationId: listPersonalAccessTokenScopes
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Scopes available to grant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatScopesListResponse'
        '400':
          $ref: '#/components/responses/XssRejected'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: The bearer token is an OAuth access token, a personal access token (`phpat_`) or a service token (`phsvc_`) rather than an interactive user session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /personal-access-tokens/{tokenId}:
    delete:
      tags:
      - Personal Access Tokens
      summary: Revoke one of your own personal access tokens
      description: |
        Revokes a token by id, scoped to `{tokenId, clientId, callerUserId}`
        — a caller can never revoke another user's token through this route,
        even though everyone in the org shares the same underlying
        `pat-system:<orgId>` client. Revocation takes effect immediately: the
        token's next verification attempt fails, including one already in
        flight.
      operationId: revokePersonalAccessToken
      security:
      - bearerAuth: []
      parameters:
      - name: tokenId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
        description: Personal access token ID
      requestBody:
        description: Optional request body for Revoke personal access token
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokePatRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RevokePatRequest'
      responses:
        '200':
          description: Personal access token revoked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokePatResponse'
        '400':
          description: |
            `tokenId` is not a 24-character hex id (`VALIDATION_ERROR` on `params.tokenId`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: The bearer token is an OAuth access token, a personal access token (`phpat_`) or a service token (`phsvc_`) rather than an interactive user session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Token not found, already revoked, not owned by the caller, or the org has no PAT app yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /personal-access-tokens/admin:
    get:
      tags:
      - Personal Access Tokens
      summary: 'Admin: list every active personal access token in the org'
      description: |
        Lists every active personal access token across every member of the
        org, paginated, with each token's owner attached (including owners
        who've since been deleted from the org — see `ownerDeleted` on
        `AdminPatListItem`). For incident response: a departed employee or a
        compromised laptop, where only the token's own creator could
        otherwise see or revoke it.

        Requires org-admin privileges (`userAdminCheck`): a non-admin caller
        gets `403` (`ForbiddenError`, message
        "You need admin access to do this. Ask an admin in your organisation.").
        The admin check runs before the query is validated, so a non-admin gets
        `403` even for an invalid `page` or `limit`. Query parameters other than
        `page` and `limit` are ignored. A page past the end answers `200` with an
        empty `data` array.
      operationId: adminListPersonalAccessTokens
      security:
      - bearerAuth: []
      parameters:
      - name: page
        in: query
        allowEmptyValue: true
        schema:
          type: integer
          minimum: 1
          default: 1
        description: Page number (defaults to `1` when omitted or empty)
      - name: limit
        in: query
        allowEmptyValue: true
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: Items per page (defaults to `100` when omitted or empty; max 100)
      responses:
        '200':
          description: Every active personal access token in the org
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminPatListResponse'
        '400':
          description: |
            `page` or `limit` is not a whole number in range (`VALIDATION_ERROR` on `query.page` / `query.limit`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: The caller is not an admin of this organization, or the bearer token is an OAuth access token, a personal access token or a service token rather than an interactive user session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /personal-access-tokens/admin/{tokenId}:
    delete:
      tags:
      - Personal Access Tokens
      summary: 'Admin: revoke any user''s personal access token by id'
      description: |
        Revokes a token by id, scoped to the org's PAT client but **not** to
        a specific owning user — the admin counterpart to
        `DELETE /personal-access-tokens/{tokenId}`. Requires org-admin
        privileges (`userAdminCheck`); a non-admin caller gets `403`
        (`ForbiddenError`), same as `GET /personal-access-tokens/admin`.
      operationId: adminRevokePersonalAccessToken
      security:
      - bearerAuth: []
      parameters:
      - name: tokenId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-fA-F0-9]{24}$
        description: Personal access token ID
      requestBody:
        description: Optional request body for Admin revoke personal access token
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevokePatRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/RevokePatRequest'
      responses:
        '200':
          description: Personal access token revoked successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevokePatResponse'
        '400':
          description: |
            `tokenId` is not a 24-character hex id (`VALIDATION_ERROR` on `params.tokenId`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '403':
          description: The caller is not an admin of this organization, or the bearer token is an OAuth access token, a personal access token or a service token rather than an interactive user session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Token not found in this org, already revoked, or the org has no PAT app yet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationJsonErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthClientManagementRateLimitError'
  /userAccount/initAuth:
    post:
      tags:
      - User Account
      summary: Initialize authentication session
      description: |
        Start a server-side authentication session and discover which sign-in methods are
        configured for the organization. This is the first step in the multi-step login flow.

        **Request body (optional)**

        - You may omit the body, send an empty JSON object `{}`, or send `{ "email": "..." }`.
        - `email` in the body is optional and kept for legacy reasons; omitting it does not prevent
          initialization. The web client typically calls this endpoint without a body and sends
          `email` on `/authenticate` instead.
        - When provided, `email` is stored on the session for correlation with subsequent steps.

        **Flow:**

        1. Call this endpoint (optional JSON body as above).
        2. Receive a session token in the `x-session-token` response header.
        3. Send that token on subsequent `/authenticate` requests (`x-session-token` header).
        4. Use `allowedMethods` and `authProviders` from the response to render the login UI.

        **Session token**

        - Returned as header `x-session-token`.
        - Required for `/authenticate` (and related steps) until it expires.

        **Multi-factor authentication**

        If the organization has MFA, complete multiple authentication steps; each step may
        return the next step's allowed methods.
      operationId: initAuth
      security: []
      requestBody:
        description: |
          Optional. Omit entirely or send `{}`. You may include `email` for legacy compatibility (pre-fills the session); invalid `email` format is rejected when the field is present.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InitAuthRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/InitAuthRequest'
        required: false
      responses:
        '200':
          description: Authentication session initialized successfully
          headers:
            x-session-token:
              schema:
                type: string
              description: Session token for subsequent authentication requests. Store this securely.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitAuthResponse'
        '400':
          description: |
            Invalid request (e.g. malformed `email` when that property is sent)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded — per-IP auth endpoint limiter (MAX_AUTH_REQUESTS_PER_MINUTE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /userAccount/authenticate:
    post:
      tags:
      - User Account
      summary: Authenticate user with credentials
      description: |
        Authenticate a user using the specified method and credentials.
        Requires a valid session token from `/initAuth`.

        **Credential Formats by Method:**

        - `password`: `{ "credentials": { "password": "your-password" } }`
        - `otp`: `{ "credentials": { "otp": "123456" } }` (6-digit code, valid for 10 minutes)
        - `google`: `{ "credentials": "google-id-token-string" }`. The object form
          `{ "credentials": { "credential": "..." } }` passes the first token check, but by code
          reading the second check is handed the whole object, so it ends in `500`
        - `microsoft`: `{ "credentials": { "idToken": "..." } }` (only `idToken` is read)

        SAML (`samlSso`), generic OAuth (`oauth`) and Azure AD (`azureAd`) sign-in were removed in 1.0;
        this endpoint answers `400` for them. Azure AD accounts sign in with `microsoft`.

        **Multi-Step Response:**

        If organization uses MFA, successful authentication returns:
        - `status: "success"` with `nextStep` and `allowedMethods` for next step

        **Fully Authenticated Response:**

        After completing all steps:
        - `message: "Fully authenticated"` with `accessToken` (1hr) and `refreshToken` (7d)

        **Security:**

        - Account locks for 24 hours after 10 consecutive failed attempts, and the owner is
          sent an email saying so. While it is locked, sign-in is refused with the same answer
          as a wrong password or code, even when the password or code is right
        - CAPTCHA may be required if enabled (pass `cf-turnstile-response`)
        - An email with no account gets the same status and message as a real account given
          a wrong password (`400`) or a wrong, missing or expired sign-in code (`401`)
        - The session token is single-use for the final step: once tokens are returned the
          session is gone, and sending it again answers `401`

        **Order of checks:** the session token is checked before the body, so a request
        without a valid `x-session-token` answers `401` whatever its body holds.
      operationId: authenticate
      security: []
      parameters:
      - name: x-session-token
        in: header
        required: true
        description: Session token received from `/initAuth` endpoint
        schema:
          type: string
      requestBody:
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AuthenticateRequest'
        required: true
      responses:
        '200':
          description: Authentication step successful or fully authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticateResponse'
        '400':
          description: |
            Bad request. Possible causes:
            - The body fails validation (`VALIDATION_ERROR`): `method` or `credentials` missing or empty, a credential field that is not a string, a malformed or over-long `email`, an unknown top-level field, or a body that is not a JSON object
            - `method` is not one the session's current step allows, including a method removed in 1.0 (`samlSso`, `oauth`, `azureAd`)
            - `github`, which has no sign-in flow
            - Wrong or missing password. A wrong password, an email with no account and a locked account all get the same message
            - Microsoft: no `idToken` (an `accessToken` alone is not read), or no client ID saved for it

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            Unauthorized. Possible causes:
            - No `x-session-token` header, or a session that is unknown, expired or already used to finish a sign-in; start again with `/initAuth`
            - Wrong, missing, expired or already used sign-in code (the same message for an email with no account and for a locked account)
            - CAPTCHA refused
            - The identity provider rejected the sign-in, or a Microsoft `idToken` is not a valid token for the saved client ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded — per-IP auth endpoint limiter (MAX_AUTH_REQUESTS_PER_MINUTE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '500':
          description: |
            Internal server error. Also returned for a password or code sign-in when neither
            the session nor the body carries an email (the account lookup fails), for a
            Google token that is not a JWT (the Google library's error is not mapped).

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /userAccount/refresh/token:
    post:
      tags:
      - User Account
      summary: Refresh access token
      description: |
        Get a new access token using a valid refresh token.

        **Usage:**

        - Pass the refresh token as a Bearer token in the Authorization header
        - Returns a new access token and basic user information
        - The request body and query string are not read

        **Token Lifetimes:**

        - Access token: 24 hours (configurable via `ACCESS_TOKEN_EXPIRY` environment variable)
        - Refresh token: 30 days (configurable via `REFRESH_TOKEN_EXPIRY` environment variable)

        **Best Practices:**

        - Call this endpoint before the access token expires
        - Store the new access token and continue using it for authenticated requests
        - If refresh fails with 401, redirect user to login flow
      operationId: refreshToken
      security:
      - scopedToken: []
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshTokenResponse'
        '400':
          description: |
            The account is locked after repeated failed sign-ins

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            The user must sign in again. Either the refresh token is missing, invalid,
            expired or of another kind (an access token, another scope), or the session was
            ended by signing out or a password change.

            If the account has been deleted or disabled, or the token names an account that
            does not exist, the message is "Your account is no longer active. Contact your
            admin." Signing in again will not help until an admin restores the account.

            An account without a stored credentials record is not refused: the record is
            created and the refresh succeeds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /userAccount/password/status:
    get:
      tags:
      - User Account
      summary: Get password status
      description: Returns whether the authenticated user has a password set. Users who signed in only through SSO do not.
      operationId: getPasswordStatus
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Password status
          content:
            application/json:
              schema:
                type: object
                required:
                - hasPassword
                properties:
                  hasPassword:
                    type: boolean
        '401':
          description: Invalid or expired access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /userAccount/password/setup/email:
    post:
      tags:
      - User Account
      summary: Email a link to set a first password
      description: |
        Sends the authenticated user a single-use link, to the email on their account, for setting a first password.
        For users who have no password yet, for example those who signed in with Google. Users who already have one change it with `POST /userAccount/password/reset`.
      operationId: sendPasswordSetupEmail
      security:
      - bearerAuth: []
      responses:
        '200':
          description: The link was sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: string
                    example: mail sent
        '400':
          description: The user already has a password
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or expired access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The user no longer exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /userAccount/password/reset:
    post:
      tags:
      - User Account
      summary: Reset password
      description: |
        Reset the password for the currently authenticated user.

        **Overview:**

        Allows a logged-in user to change their password by providing the current password and a new password.

        **Order of checks:** the access token is read before the body, so a request without
        an `Authorization` header answers `400` whatever its body holds. Body fields other
        than the three below are dropped by the validator, and the query string is not read.

        **Effect on sessions:** the change ends refresh tokens issued before it. The response
        carries a new access token.
      operationId: resetPassword
      security:
      - bearerAuth: []
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - currentPassword
              - newPassword
              properties:
                currentPassword:
                  type: string
                  format: password
                  minLength: 1
                  description: The password the account has now. The validator treats it as optional; the handler then refuses a missing or empty value with `400`.
                newPassword:
                  type: string
                  format: password
                  minLength: 1
                  description: |
                    The new password: at least 8 characters with an uppercase letter, a
                    lowercase letter, a digit and one of `#?!@$%^&*-`, at most 72 bytes, and
                    different from the current one. A value that breaks these rules is
                    refused by the handler with `400`.
                cf-turnstile-response:
                  type: string
                  description: Cloudflare Turnstile CAPTCHA token (required when Turnstile is configured server-side)
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              required:
              - currentPassword
              - newPassword
              properties:
                currentPassword:
                  type: string
                  format: password
                  minLength: 1
                  description: The password the account has now. The validator treats it as optional; the handler then refuses a missing or empty value with `400`.
                newPassword:
                  type: string
                  format: password
                  minLength: 1
                  description: |
                    The new password: at least 8 characters with an uppercase letter, a
                    lowercase letter, a digit and one of `#?!@$%^&*-`, at most 72 bytes, and
                    different from the current one. A value that breaks these rules is
                    refused by the handler with `400`.
                cf-turnstile-response:
                  type: string
                  description: Cloudflare Turnstile CAPTCHA token (required when Turnstile is configured server-side)
      responses:
        '200':
          description: Password reset successfully - returns new access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticatedPasswordResetResponse'
        '400':
          description: |
            Bad request. Possible causes:
            - No `Authorization` header, or one with no token after the scheme (checked before the body)
            - The body fails validation (`VALIDATION_ERROR`): `newPassword` missing or not a string, `currentPassword` or `cf-turnstile-response` not a string, or no JSON object body
            - `currentPassword` missing or empty, or `newPassword` empty
            - Current and new password are the same (plain-text comparison)
            - New password does not meet strength requirements (min 8 chars, uppercase, lowercase, number, special character, at most 72 bytes)
            - Old and new password are the same (hash comparison against stored password)
            - Account is blocked due to too many incorrect login attempts

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            Unauthorized. Possible causes:
            - Current password is incorrect
            - Invalid CAPTCHA verification (when Turnstile is configured)

            An access token that cannot be verified is not answered here but with `500`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Not found. Possible causes:
            - User credentials not found (no password set for account)
            - Auth container not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded — per-IP auth endpoint limiter (MAX_AUTH_REQUESTS_PER_MINUTE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitErrorResponse'
        '500':
          description: |
            Internal server error. Also returned when the bearer token cannot be verified
            (not a JWT, signed with another key such as a refresh token, or expired): the
            verification error is not mapped to `401`.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orgAuthConfig/authMethods:
    get:
      tags:
      - Organization Auth Config
      summary: Get organization authentication methods
      description: |
        Retrieve the configured authentication methods for the organization.

        **Response Structure:**

        Returns an array of authentication steps, each containing:
        - `order`: The step's position, 1, 2 or 3. Steps are returned in ascending order of the
          `order` they were saved with and renumbered from 1. A method removed in 1.0 is left out
          (`azureAd` reads as `microsoft`), a step left with no method is dropped, and when a
          removed method was left out `password` is added to the first step
        - `allowedMethods`: Array of methods allowed for that step

        **Example Response:**

        ```json
        {
          "authMethods": [
            { "order": 1, "allowedMethods": [{ "type": "password" }, { "type": "google" }] },
            { "order": 2, "allowedMethods": [{ "type": "otp" }] }
          ]
        }
        ```

        **Admin Access Required:** Only organization admins can view auth configuration, with
        a session access token. The query string is not read.
      operationId: getAuthMethods
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Authentication methods retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthConfig'
        '400':
          description: |
            No `Authorization` header, or one with no token after the scheme

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            The token does not belong to an active admin of the organization it names: a member,
            an admin of another organization, or a token issued to an OAuth app
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Not found. Possible causes:
            - The token carries no `userId` or no `orgId` (`Account not found`)
            - The organization has no sign-in configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error. Also returned when the bearer token cannot be verified
            (not a JWT, signed with another key, or expired): the verification error is not
            mapped to `401`.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orgAuthConfig/updateAuthMethod:
    post:
      tags:
      - Organization Auth Config
      summary: Update organization authentication methods
      description: |
        Update the authentication methods configuration for an organization.
        This allows admins to configure single or multi-factor authentication.

        **Validation Rules:**
        - Minimum 1 step, maximum 3 steps
        - Each step must have a unique `order`. `order` is only checked to be a number and is
          stored as sent; sign-in runs the steps in ascending `order`
        - No duplicate methods within the same step
        - No method can appear in multiple steps
        - Each step must have at least one allowed method
        - `samlSso` and `oauth` were removed in 1.0 and are refused; use `microsoft` in place of `azureAd`

        The two rules that compare steps with each other (unique `order`, a method in only one
        step) are not expressed in the request schema below; the API refuses a request that
        breaks them with `400 VALIDATION_ERROR` naming `body.authMethod`.

        Unknown fields, at any level of the body, and any query string are dropped by the
        validator, not refused.

        **Available Methods:**
        - `password`: Email/password authentication
        - `otp`: One-time password via email
        - `google`: Google OAuth 2.0
        - `microsoft`: Microsoft OAuth 2.0

        **Example - Single Factor (Password or Google):**

        ```json
        {
          "authMethod": [
            { "order": 1, "allowedMethods": [{ "type": "password" }, { "type": "google" }] }
          ]
        }
        ```

        **Example - Two Factor (Password + OTP):**

        ```json
        {
          "authMethod": [
            { "order": 1, "allowedMethods": [{ "type": "password" }] },
            { "order": 2, "allowedMethods": [{ "type": "otp" }] }
          ]
        }
        ```

        **Admin Access Required:** Only organization admins can update auth configuration.
      operationId: updateAuthMethod
      security:
      - bearerAuth: []
      requestBody:
        description: Request payload
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - authMethod
              properties:
                authMethod:
                  type: array
                  description: Authentication steps to set for the organization (1-3 steps).
                  minItems: 1
                  maxItems: 3
                  items:
                    $ref: '#/components/schemas/AuthStep'
      responses:
        '200':
          description: Authentication methods updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateAuthMethodResponse'
        '400':
          description: |
            Bad request. Possible causes:
            - No `Authorization` header, or one with no token after the scheme (checked before the body)
            - The body fails validation (`VALIDATION_ERROR`): `authMethod` missing or not an array,
              no steps or more than 3, a step with no methods, a method twice in one step or in two
              steps, an unknown method type, an `order` that is missing, repeated or not a number,
              or a body that is not a JSON object
            - A method removed in 1.0 (`samlSso`, `oauth`) or the old name `azureAd`
              (`VALIDATION_ERROR`): `"samlSso" sign-in was removed in PipesHub 1.0. Use password,
              email OTP, Google or Microsoft sign-in instead.` or `"azureAd" sign-in is now
              "microsoft". Use "microsoft" instead.`

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            The token does not belong to an active admin of the organization it names: a member,
            an admin of another organization, or a token issued to an OAuth app
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Not found. Possible causes:
            - The token carries no `userId` or no `orgId` (`Account not found`)
            - The organization has no sign-in configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error. Also returned when the bearer token cannot be verified
            (not a JWT, signed with another key, or expired): the verification error is not
            mapped to `401`.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /orgAuthConfig:
    post:
      tags:
      - Organization Auth Config
      summary: Set up auth configuration
      description: |
        Set up or initialize the organization's authentication configuration.

        First-run only: when the deployment already has a sign-in configuration the answer is
        `200` with `Org config already done`, and the request body is not read at all (a missing
        body, missing or mistyped fields and unknown fields are all accepted). The route has no
        validator; the body fields below are the ones read when the organization is created.
        The query string is not read.
      operationId: setUpAuthConfig
      security:
      - bearerAuth: []
      requestBody:
        required: true
        description: Organization setup details
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrgAuthConfigCreateRequest'
      responses:
        '200':
          description: Auth configuration already exists for this deployment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthConfigSetupResponse'
        '201':
          description: Auth configuration created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthConfigSetupResponse'
        '400':
          description: |
            No `Authorization` header, or one with no token after the scheme

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            The token does not belong to an active admin of the organization it names: a member,
            an admin of another organization, or a token issued to an OAuth app
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The token carries no `userId` or no `orgId` (`Account not found`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error. Also returned when the bearer token cannot be verified
            (not a JWT, signed with another key, or expired): the verification error is not
            mapped to `401`.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /org:
    get:
      tags:
      - Organizations
      summary: Get current organization
      description: |
        Retrieve details about the authenticated user's organization.

        **Overview:**

        This endpoint returns the organization document for the current user's org, including profile data and configuration.

        **Response Includes:**

        - Organization profile (registeredName, shortName, contactEmail, domain)
        - Account type
        - Onboarding status
        - Permanent address
        - Creation and modification timestamps

        **Use Cases:**

        - Organization profile pages
        - Settings and configuration screens
      operationId: getCurrentOrganization
      security:
      - bearerAuth: []
      - oauth2:
        - org:read
      responses:
        '200':
          description: Organization details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '400':
          $ref: '#/components/responses/XssRejected'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: 'An OAuth access token without the `org:read` scope is refused: `Insufficient scope. Required: org:read`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Organization not found - User's organization does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error - Database query failure.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase:
    post:
      tags:
      - Knowledge Base
      summary: Create a new knowledge base
      description: |
        Create a new knowledge base for organizing and managing documents within your organization.

        **Overview:**

        A knowledge base is a container for organizing related documents, files, and content. It provides a central location for teams to collaborate on shared information.

        **Features:**

        - Hierarchical folder structure support
        - Role-based access control (OWNER, WRITER, READER)
        - Full-text search across all records
        - Integration with external connectors (Google Drive, OneDrive, etc.)
        - Automatic content indexing for AI-powered search

        **Naming Rules:**

        - Name must be 1-255 characters and hold at least one character that is not whitespace
        - Whitespace around the name is removed before it is stored
        - A name that contains an HTML tag, a `javascript:` URL or an inline event handler
          (`onclick=` and the like) is refused with `400`; nothing is stripped out of it
        - Names don't need to be unique within organization

        **Request body:**

        Only `kbName` is read. Any other field is dropped before the handler runs, so a
        knowledge base cannot be created hidden, or with another role or organization,
        through this endpoint.

        **Creator Permissions:**

        The user creating the KB automatically becomes the OWNER with full administrative rights.
      operationId: createKnowledgeBase
      security:
      - bearerAuth: []
      - oauth2:
        - kb:write
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              type: object
              properties:
                kbName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  pattern: \S
                  description: |
                    Name of the knowledge base. Leading and trailing whitespace is removed
                    first, so a name made only of whitespace is refused as empty.
                  example: Product Documentation
              required:
              - kbName
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                kbName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  pattern: \S
                  description: |
                    Name of the knowledge base. Leading and trailing whitespace is removed
                    first, so a name made only of whitespace is refused as empty.
                  example: Product Documentation
              required:
              - kbName
      responses:
        '200':
          description: Knowledge base created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseCreateResponse'
        '400':
          description: |
            **Invalid request:**

            - `kbName` missing, `null`, not a string, empty or only whitespace, or longer
              than 255 characters (`VALIDATION_ERROR`, with the field named in `metadata.errors`)
            - The body is missing or is not a JSON object (`VALIDATION_ERROR`)
            - `kbName` contains an HTML tag, a `javascript:` URL or an inline event handler
              (`HTTP_BAD_REQUEST`). This check runs before authentication.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Possible reasons:

            - OAuth token lacks the `kb:write` scope
            - Connector service denied the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found - Authenticated user does not exist in the graph database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error - Knowledge base creation failed in connector or database.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable - Connector service is unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Knowledge Base
      summary: List all knowledge bases
      description: |
        Retrieve a paginated list of all knowledge bases accessible to the authenticated user.

        **Overview:**

        Returns knowledge bases where the user has at least READER permission. Results include the user's role for each KB.

        **Filtering:**

        - **search:** Full-text search on KB names (max 1000 chars). A longer value is answered `500`, not `400`.
        - **permissions:** Filter by user's role (comma-separated: OWNER, WRITER, READER)

        **Sorting Options:**

        - `name` — Alphabetical by KB name
        - `createdAtTimestamp` — By creation date
        - `updatedAtTimestamp` — By last modification
        - `userRole` — By permission level

        **Performance:**

        Uses efficient pagination with limit/offset. For large result sets, use smaller page sizes.

        **Query parameters:**

        Only `page`, `limit`, `search`, `permissions`, `sortBy`, and `sortOrder` are allowed; any other
        query key is rejected with `400` (`VALIDATION_ERROR`: "These fields aren't accepted here: <key>.").
        A parameter sent more than once is rejected the same way. `page`, `limit`, `search`,
        `permissions` and `sortBy` sent with an empty value are read as not sent; an empty
        `sortOrder` is rejected.
      operationId: listKnowledgeBases
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      parameters:
      - name: page
        in: query
        required: false
        description: |
          Page number (1-indexed). Omitted or empty values default to 1. A page past the last
          one returns an empty list. The value is read with JavaScript `parseInt`, so text after
          leading digits is ignored (`1abc` is page 1); send a plain integer.
        allowEmptyValue: true
        schema:
          type: integer
          minimum: 1
          maximum: 90071992547409
          default: 1
      - name: limit
        in: query
        required: false
        description: |
          Results per page (max 100). Omitted or empty values default to 20. Read with
          JavaScript `parseInt` like `page`.
        allowEmptyValue: true
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: search
        in: query
        required: false
        description: |
          Search KB names (max 1000 chars after trimming). Rejected with `400` if it contains
          HTML/script tags, event handlers or `javascript:` (`HTTP_BAD_REQUEST`), or a
          printf-style format specifier (`VALIDATION_ERROR`). The format-specifier check
          also catches ordinary text such as `50% discount` (`%`, a space, then a letter
          like `d`). A value longer than 1000 characters is answered `500`.
        schema:
          type: string
          maxLength: 1000
          pattern: ^(?![\s\S]*?(?:%(?:\d{1,10}[!$]|[#0\-+ ]{0,10}\d{0,10}\.?\d{0,10}[diouxXeEfFgGaAcspn%]|\d{1,10}[a-zA-Z])))
      - name: permissions
        in: query
        required: false
        description: |
          Comma-separated permission roles to filter by. Each token must be exactly one of
          OWNER, WRITER, READER: upper case, with no space around the commas. Empty tokens
          (`OWNER,,WRITER,`) are dropped, but a value with no role at all (`,`) is rejected.
          An empty value is read as not sent.
        allowEmptyValue: true
        schema:
          type: string
          pattern: ^(OWNER|WRITER|READER)(,(OWNER|WRITER|READER))*$
          example: OWNER,WRITER
      - name: sortBy
        in: query
        required: false
        description: Field to sort by. An empty value is read as the default.
        allowEmptyValue: true
        schema:
          type: string
          enum:
          - name
          - createdAtTimestamp
          - updatedAtTimestamp
          - userRole
          default: name
      - name: sortOrder
        in: query
        required: false
        description: Sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllKnowledgeBaseResponseSchema'
        '400':
          description: |
            **Invalid query parameters:**

            - `page` not a positive integer, or greater than 90071992547409
            - `limit` not between 1 and 100
            - Unknown query parameter (only `page`, `limit`, `search`, `permissions`, `sortBy`, `sortOrder` allowed)
            - A parameter sent more than once
            - Invalid `sortBy` or `sortOrder` (an empty `sortOrder` included)
            - Invalid `permissions` role token
            - `search` contains HTML/scripts/format specifiers
            - Connector returned a 400 error

            Checks made by the request validator answer `VALIDATION_ERROR`; an out-of-range
            `page`, an invalid `permissions` token and HTML in `search` answer `HTTP_BAD_REQUEST`.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Possible reasons:

            - OAuth token lacks the `kb:read` scope
            - Connector service denied the request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: User not found — authenticated user does not exist in the graph database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error — listing knowledge bases failed in connector or database.
            Also returned (`INTERNAL_ERROR`) when `search` is longer than 1000 characters.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable — connector service is unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/{kbId}:
    get:
      tags:
      - Knowledge Base
      summary: Get knowledge base by ID
      description: |
        Retrieve detailed information about a specific knowledge base.

        **Overview:**

        Returns complete KB metadata including name, timestamps, every folder (nested ones
        included, without their parent), and the requesting user's role.

        **Access Control:**

        User must have at least READER permission to view KB details. A knowledge base the
        caller holds no role on is answered `404` with the same message as an unknown id, so
        its existence is not revealed.

        **Request:** only the `kbId` path parameter is read; any query string or body is ignored.
      operationId: getKnowledgeBase
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      parameters:
      - name: kbId
        in: path
        required: true
        description: |
          Knowledge base ID (non-empty string). It is not checked to be a UUID: any other
          value is looked up and answered `404`.
        schema:
          type: string
          minLength: 1
          example: 8a095180-2989-4018-b448-70eb75fba1c7
      responses:
        '200':
          description: Knowledge base retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetKnowledgeBaseById'
        '400':
          description: |
            `kbId` holds a character that cannot stand in a URL path segment (`/`, `\`, `?`,
            `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden: the OAuth token lacks the `kb:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            `Knowledge base not found`. Possible reasons:

            - Knowledge base does not exist (any id, UUID or not)
            - The caller holds no role on the knowledge base
            - Authenticated user does not exist in the graph database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error — retrieving knowledge base failed in connector or database.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable — connector service is unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - Knowledge Base
      summary: Update knowledge base
      description: |
        Update a knowledge base's name.

        **Required permission:**

        User must have one of `OWNER` or `WRITER` on the knowledge base.

        **Validation:**

        - `kbId` path parameter must be a valid UUID (`updateKBSchema`)
        - `kbName` is trimmed first, then must be 1–255 characters
        - A `kbName` holding an HTML tag, a `javascript:` URL or an inline event handler is
          refused with `400` before authentication; one holding a printf-style format
          specifier (`%s`, `%n`, `%x`, `%p`, with flags and width such as `%08x`) is refused
          with `400` by the gateway controller. A plain `%` (`50% off`) is accepted.
        - `kbName` is the only field read. Other body fields and any query parameter are
          ignored, so a body without `kbName` (an empty object, no body, or only unknown
          fields) is refused by the connector service with `400` `No fields to update`.
      operationId: updateKnowledgeBase
      security:
      - bearerAuth: []
      - oauth2:
        - kb:write
      parameters:
      - name: kbId
        in: path
        required: true
        description: Knowledge base ID (UUID)
        schema:
          type: string
          format: uuid
          example: 8a095180-2989-4018-b448-70eb75fba1c7
      requestBody:
        required: true
        description: The new name. `kbName` is the only field and it is required.
        content:
          application/json:
            schema:
              type: object
              required:
              - kbName
              properties:
                kbName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]))[\s\S]*?\S
                  description: |
                    New name for the knowledge base. Whitespace around it is removed first, so
                    a name made only of whitespace is refused as empty.
                  example: Updated Documentation Hub
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - kbName
              properties:
                kbName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]))[\s\S]*?\S
                  description: |
                    New name for the knowledge base. Whitespace around it is removed first, so
                    a name made only of whitespace is refused as empty.
                  example: Updated Documentation Hub
      responses:
        '200':
          description: Knowledge base updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateKnowledgeBaseById'
        '400':
          description: |
            Invalid request. Possible reasons:

            - `kbId` is not a valid UUID, or `kbName` is `null`, not a string, empty or only
              whitespace, or longer than 255 characters (`VALIDATION_ERROR`)
            - `kbName` contains an HTML tag, a `javascript:` URL or an inline event handler
              (`HTTP_BAD_REQUEST`). This check runs before authentication.
            - `kbName` contains a format specifier (`HTTP_BAD_REQUEST`)
            - The body has no `kbName` (`HTTP_BAD_REQUEST`, `No fields to update`)
            - `kbId` holds a character that cannot stand in a URL path segment
              (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Possible reasons:

            - OAuth token lacks the `kb:write` scope
            - User role is insufficient (`READER`; requires `OWNER` or `WRITER`)

            A caller with no role on the knowledge base gets `404`, not `403`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Not found. Possible reasons:

            - Knowledge base does not exist
            - The caller holds no role on the knowledge base (same message,
              `Knowledge base not found`)
            - Authenticated user does not exist in the graph database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error — updating knowledge base failed in connector or database.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable — connector service is unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Knowledge Base
      summary: Delete knowledge base
      description: |
        Permanently delete a knowledge base and all its contents.

        **Required permission:**

        User must have `OWNER` role on the knowledge base.

        **What gets deleted:**

        - All folders within the KB
        - All records and their indexed content
        - All permission grants
        - Associated storage files

        **Warning:** This action is irreversible. Consider exporting data before deletion.

        **Request:** only the `kbId` path parameter is read; any query string or body is ignored.
      operationId: deleteKnowledgeBase
      security:
      - bearerAuth: []
      - oauth2:
        - kb:delete
      parameters:
      - name: kbId
        in: path
        required: true
        description: Knowledge base ID (non-empty string)
        schema:
          type: string
          minLength: 1
          example: 8a095180-2989-4018-b448-70eb75fba1c7
      responses:
        '200':
          description: Knowledge base deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteKnowledgeBaseById'
        '400':
          description: |
            `kbId` holds a character that cannot stand in a URL path segment (`/`, `\`, `?`,
            `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Possible reasons:

            - OAuth token lacks the `kb:delete` scope
            - User is `WRITER` or `READER`: `Only KB owners can delete knowledge bases`

            A caller with no role on the knowledge base gets `404`, not `403`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Not found. Possible reasons:

            - Knowledge base does not exist, or was already deleted (any id, UUID or not)
            - The caller holds no role on the knowledge base (same message,
              `Knowledge base not found`)
            - Authenticated user does not exist in the graph database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error — deleting knowledge base failed in connector or database.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable — connector service is unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/record/{recordId}:
    get:
      tags:
      - Knowledge Base
      summary: Get record by ID
      description: |
        Retrieve detailed information about a specific record.

        **Overview:**

        Returns complete record metadata including name, type, indexing status, storage information, and version history.

        **Query parameters:**

        `convertTo` and `version` are checked by the request validator but not used by this
        endpoint: the response is the same JSON metadata whatever they hold. They take effect
        on `GET /knowledgeBase/stream/record/{recordId}`, which shares the validator. Any other
        query parameter is ignored.

        **Not found:**

        A record that does not exist, one the caller has no access to and one that is in the
        trash all answer `404` with the same message, so a record's existence is not revealed.
      operationId: getRecordById
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      parameters:
      - name: recordId
        in: path
        required: true
        description: Record ID
        schema:
          type: string
      - name: convertTo
        in: query
        description: Accepted as any single string and not used by this endpoint (no conversion happens here). Sending it more than once is rejected with `400`.
        schema:
          type: string
          example: txt
      - name: version
        in: query
        description: 'Registry version number of an artifact record: digits only. Checked and then not used by this endpoint; a value that is not all digits (empty, negative or decimal included) is rejected with `400`.'
        schema:
          type: string
          pattern: ^\d+$
          example: '2'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRecordByIdResponseSchema'
        '400':
          description: |
            - `version` is not all digits, or `convertTo`/`version` is sent more than once (`VALIDATION_ERROR`)
            - `recordId` holds a character that cannot stand in a URL path segment
              (`/`, `\`, `?`, `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: OAuth token is missing the required kb:read scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Record not found, not accessible to the caller, or in the trash. The message is
            `Record <recordId> not found` in every case.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while retrieving record details.

            Current API behavior includes record-access lookup failures returning
            `HTTP_INTERNAL_SERVER_ERROR` with messages such as
            `Failed to check record access`, including cases where callers might
            otherwise expect a not-found style response.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - Knowledge Base
      summary: Update record
      description: |
        Update a record's name and/or file content.

        **Overview:**

        Allows updating the display name and optionally replacing the file content. Triggers re-indexing when content changes.

        **Required permission:**

        WRITER or higher on the record's knowledge base. A READER is answered `403`; a caller
        with no role is answered `404`.

        **Renaming:**

        Send `recordName` as a multipart field or in a JSON body. There is no length limit.
        A request with no body, an empty JSON object or an empty `recordName` changes nothing
        and still answers `200`. In a JSON body the name is trimmed first (so a blank name is
        read as empty and changes nothing); in a multipart form it is not, and a blank name
        is refused with `400`. Fields other than `recordName` and `file` are ignored.

        **Updating file content:**

        Include a new file in a multipart request to replace the existing content. The file
        extension must match the original: a file with another extension is answered `500`,
        not `400`. When a file is sent, `recordName` is ignored and the record is named after
        the file (without its extension).

        **Side effects:**

        - Updates `updatedAtTimestamp`
        - A new file is stored as the next version of the record's storage document and the
          record is queued for indexing again. The record's own `version` and `sizeInBytes`
          are not updated by this call.

        **Known gaps:**

        - Renaming a record that is in the trash is not refused: the answer is `200` with the
          success message, but nothing changes, and `record` is the trashed record (`isDeleted: true`,
          with `deletedAtTimestamp`, `deleteBatchId` and `deleteSource`).
        - `fileBuffer` is an internal field filled by the upload parser. A JSON body that
          supplies an object under that name (`buffer`, `originalname`, `mimetype`, `size`,
          `lastModified`) is treated as an uploaded file and stored as the new version.

        **OAuth scopes:** `kb:write`, plus `kb:read`: replacing the file first reads the record and its knowledge base with the caller's token.
      operationId: updateRecord
      security:
      - bearerAuth: []
      - oauth2:
        - kb:write
        - kb:read
      parameters:
      - name: recordId
        in: path
        required: true
        description: Record ID
        schema:
          type: string
      requestBody:
        description: 'Request payload. Optional: without one nothing changes.'
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                recordName:
                  type: string
                  description: |
                    New name for the record. Ignored when `file` is sent. Must not contain
                    HTML, an inline event handler or a printf-style format specifier.
                file:
                  type: string
                  format: binary
                  description: Replacement file content; at most one file, with the stored file's extension.
          application/json:
            schema:
              type: object
              properties:
                recordName:
                  type: string
                  description: New name for the record (rename only; a file needs the multipart form).
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                recordName:
                  type: string
                  description: New name for the record (rename only; a file needs the multipart form).
      responses:
        '200':
          description: Record updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateRecordResponseSchema'
        '400':
          description: |
            - JSON body: `recordName` is not a string, or the body is not an object (`VALIDATION_ERROR`)
            - `recordName` contains HTML, an inline event handler or a format specifier such as `%s`
            - Multipart `recordName` is only whitespace (`Record name cannot be empty`)
            - More than one file, or a file sent under a field name other than `file`
            - `recordId` holds a character that cannot stand in a URL path segment
              (`/`, `\`, `?`, `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            OAuth token lacks the `kb:write` scope, or `kb:read` when a replacement file is sent; or the caller is only a READER
            on the record's knowledge base (`User lacks permission to edit records` for a rename,
            `You do not have permission to upload to this knowledge base` when a file is sent).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Record not found, or the caller has no role on its knowledge base
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while updating record. Also returned when the replacement
            file's extension differs from the stored file's: storage refuses the upload and the
            failure is reported as `HTTP_INTERNAL_SERVER_ERROR` ("...tried to save this file...").


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Another file with the new name already exists in the same folder

            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Knowledge Base
      summary: Delete record
      description: |
        Delete a record from the knowledge base.

        **Required permission:**

        WRITER or higher on the record's knowledge base. A READER is answered `403`; a caller
        with no role, an unknown id and a record that is already in the trash are all answered `404`.
        The query string and any request body are ignored.

        **What gets deleted:**

        - Record metadata
        - Associated storage file
        - Indexed content and embeddings

        **Trash:** With "Move Deleted Records to the Trash" on in Labs, the record
        goes to the trash instead: it disappears from search, chat and lists at once,
        its embeddings are removed, and the record and its file stay until the scheduled
        purge. The response then carries `softDeleted: true` and the `batchId`, and the
        record can be brought back with `POST /knowledgeBase/record/{recordId}/restore`.
        With the setting off, the delete is immediate and cannot be undone.
        A folder sent to the trash this way goes alone: the records inside it stay live and
        readable. `DELETE /knowledgeBase/{kbId}/folder/{folderId}` trashes a folder with its
        contents.
      operationId: deleteRecord
      security:
      - bearerAuth: []
      - oauth2:
        - kb:delete
      parameters:
      - name: recordId
        in: path
        required: true
        description: Record ID
        schema:
          type: string
      responses:
        '200':
          description: Record deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteRecordResponseSchema'
        '400':
          description: |
            `recordId` holds a character that cannot stand in a URL path segment
              (`/`, `\`, `?`, `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            OAuth token is missing the required kb:delete scope, or the caller is only a READER
            on the record's knowledge base (`User lacks permission to delete records`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Record not found, not accessible to the caller, or already in the trash. The message
            is `You do not have access to this record` in every case.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while deleting record.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/record/{recordId}/restore:
    post:
      tags:
      - Knowledge Base
      summary: Restore a deleted record
      description: |
        Bring a record back from the trash, together with everything deleted in the
        same action: a folder comes back with its contents, a file with its
        attachments, a multi-select delete with every item it removed.

        Needs "Move Deleted Records to the Trash" on in Labs.

        **Required permission:** the role the delete needed. A single file needs
        OWNER, WRITER or FILEORGANIZER on its collection; a folder or several items
        need OWNER or WRITER.

        **Names:** an item whose name another item next to it now uses comes back
        as "name (restored)" (a file keeps its extension: "report (restored).pdf").

        **Search:** restored files are indexed again, so they return to search and
        chat once indexing finishes. `reindexPending` lists any that could not be
        queued; reindex those by hand. A file that is back but whose indexing never
        started is queued again when it is restored again, and the indexing service
        queues it on its own after about an hour.

        A record that is not in the trash answers 200 with nothing restored.
        The query string and any request body are ignored.
      operationId: restoreRecord
      security:
      - bearerAuth: []
      - oauth2:
        - kb:delete
      parameters:
      - name: recordId
        in: path
        required: true
        description: Record ID of any item in the delete batch
        schema:
          type: string
      responses:
        '200':
          description: Record restored, with everything deleted along with it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestoreRecordResponseSchema'
        '400':
          description: |
            `recordId` holds a character that cannot stand in a URL path segment
              (`/`, `\`, `?`, `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Not allowed. The message says why and what to do: restoring is turned off
            in Labs (ask an admin to turn on "Move Deleted Records to the Trash"), the
            caller lacks edit access to the collection (ask its owner), the record comes
            from a connected app (restore it in that app; it returns at the next sync),
            or the OAuth token is missing the kb:delete scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            No such record in this workspace, or it was removed for good when the trash was emptied.
            A caller with no role on the record's collection also gets `404` (`Knowledge base not found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Nothing was restored. The message says what to do: the folder the record was
            in is still in the trash (restore that folder first), another item has taken
            this record's place (delete that item first, then restore), or the record
            changed while it was being restored (refresh and try again).

            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while restoring the record.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/records/restore:
    post:
      tags:
      - Knowledge Base
      summary: Restore several deleted records
      description: |
        Restore up to 100 records from the trash. Each id is restored as
        `POST /knowledgeBase/record/{recordId}/restore` restores it, with everything
        deleted along with it; ids from one delete are restored once. Every id gets its
        own outcome in `results`, so one refusal does not hold the others back, and the
        answer is 200 whatever the outcomes: with the trash turned off in Labs every id is
        refused with `code: 403` inside a 200. An id listed twice is answered once. Body
        fields other than `recordIds` are ignored.
      operationId: restoreRecords
      security:
      - bearerAuth: []
      - oauth2:
        - kb:delete
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreRecordsRequestBody'
      responses:
        '200':
          description: Outcome for each requested record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestoreRecordsResponseSchema'
        '400':
          description: |
            recordIds is missing, not a list, empty, or longer than 100, or one of the ids is
            not a string or is empty after trimming. Send between 1 and 100 record ids.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: OAuth token is missing the required kb:delete scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while restoring records.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/{kbId}/trash:
    get:
      tags:
      - Knowledge Base
      summary: List a collection's recently deleted items
      description: |
        One page of what was deleted from a collection and can still be restored,
        newest first. Each item is what one delete removed, as a restore brings it back
        whole: a folder deleted with its contents is one item, and so is a multi-select
        delete (`rootCount` items selected, some named in `otherRootNames`). `itemCount`
        says how many records it holds, the folder included.

        A folder deleted with `DELETE /knowledgeBase/{kbId}/folder/{folderId}` takes its
        contents along. A folder deleted with `DELETE /knowledgeBase/record/{recordId}`
        goes to the trash alone (`itemCount` 1): the records inside it stay live.
        Restore an item with `POST /knowledgeBase/record/{recordId}/restore`, using its `id`.

        Needs "Move Deleted Records to the Trash" on in Labs.

        **Who sees what:** the list holds what the caller may restore. OWNER and
        WRITER see every item; FILEORGANIZER sees single files only; other roles are
        refused. The workspace and user always come from the sign-in.

        **Removed for good:** the scheduled cleanup may remove an item from
        `removableAfterTimestamp` on (at least 14 days after it was deleted by
        default; it runs every 14 days, so an item stays 14 to 28 days). It is
        absent when the retention settings can't be read.

        An item whose folder is also in the trash (`parentInTrash`) can only be
        restored after that folder.

        **Request:** query parameters other than `page` and `limit` are ignored. A page past
        the last one is answered `200` with no items.
      operationId: listTrash
      security:
      - bearerAuth: []
      - oauth2:
        - kb:delete
      parameters:
      - name: kbId
        in: path
        required: true
        description: Collection (knowledge base) ID
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
      responses:
        '200':
          description: One page of recently deleted items
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTrashResponseSchema'
        '400':
          description: |
            page or limit is not a whole number in range, or is sent more than once (`VALIDATION_ERROR`
            naming `query.page` or `query.limit`, for example "Page must be 1 or more." or "Limit must be
            between 1 and 100."). Ask for a page from 1 up, with 1 to 100 items per page.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Not allowed. The message says why and what to do: the trash is turned off
            in Labs (ask an admin to turn on "Move Deleted Records to the Trash"), the
            caller lacks edit access to the collection (ask its owner), or the OAuth
            token is missing the kb:delete scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No such collection in this workspace, or the caller has no role on it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while listing deleted items.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/stream/record/{recordId}:
    get:
      tags:
      - Knowledge Base
      summary: Stream record content
      description: |
        Stream the binary content of a record's file.

        **Overview:**

        Returns the stored file's bytes with the file's own `Content-Type` (for an uploaded
        file, the MIME type it was uploaded with, followed by `; charset=utf-8`, for example
        `text/plain; charset=utf-8` or `application/json; charset=utf-8`). No
        `Content-Disposition` header is sent for uploaded files.

        **Use cases:**

        - File downloads
        - Inline document preview
        - Content extraction pipelines

        **Format conversion:**

        `convertTo=application/pdf` asks for a PDF rendering of documents that can be
        converted. Any other value, and the conversion request for a plain-text file, is
        ignored: the original file is returned.

        **Access:** the caller needs access to the record (any role on its knowledge base).
        Without it, and for a record in the trash, the answer is `403`. An unknown record, or
        an id that is not a record (a knowledge base id), is `404`. A folder has no content:
        the answer is `502`.

        **Errors** that come from the connector service are relayed with its status as
        `{"error": "<message>"}` (`StreamRecordErrorResponse`); errors raised by the gateway
        itself (`400`, `401`, scope `403`, malformed body `500`) use `ErrorResponse`.

        **Request:** unknown query parameters are ignored.
      operationId: streamRecordBuffer
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      parameters:
      - name: recordId
        in: path
        required: true
        description: Record ID
        schema:
          type: string
      - name: convertTo
        in: query
        description: |
          Target format for conversion. Only `application/pdf` has an effect, and only for
          documents that can be converted. Sending it more than once is refused with `400`.
        schema:
          type: string
      - name: version
        in: query
        description: |
          Registry version to pin ARTIFACT record content to. Omit to stream
          the latest version. Ignored for non-artifact records. Must be written as digits
          only; anything else (`-1`, `1.5`, an empty value) or sending it more than once is
          refused with `400`.
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: |
            The file's content, with the file's own MIME type (`text/plain`, `text/markdown`,
            `text/csv`, `text/html` and `application/json` for the text files uploads produce;
            any other stored type is passed through as well). A JSON file is sent exactly as it
            was uploaded.
          content:
            '*/*':
              schema:
                type: string
                format: binary
        '400':
          description: |
            - `version` not written as digits, or `convertTo`/`version` sent more than once
              (`VALIDATION_ERROR`)
            - `recordId` holds a character that cannot stand in a URL path segment (`/`, `\`,
              `?`, `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Returned when the OAuth token is missing the required `kb:read` scope
            (`ErrorResponse`), or as `{"error": "You do not have permission to access this record"}`
            when the caller has no access to the record or the record is in the trash.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ErrorResponse'
                - $ref: '#/components/schemas/StreamRecordErrorResponse'
        '404':
          description: |
            `{"error": "Record not found"}`: the record does not exist, belongs to another
            organization, or the id is not a record (for example a knowledge base id). Also
            returned when the organization or the backing connector is not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamRecordErrorResponse'
        '409':
          description: |
            Conflict - the connector instance for this record is disabled. Enable it from Connector Settings and try again.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamRecordErrorResponse'
        '500':
          description: |
            Internal streaming failure, downstream conversion failure, or connector/backend
            error proxied by the gateway.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/StreamRecordErrorResponse'
                - $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: |
            The record has no file content the connector service can fetch, for example a
            folder: `{"error": "Could not retrieve this item right now. Please try again later."}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StreamRecordErrorResponse'
  /knowledgeBase/{kbId}/folder:
    post:
      tags:
      - Knowledge Base
      summary: Create folder
      description: |
        Create a folder in a knowledge base. Omit `folderId` to create at the KB root;
        pass `folderId` as a query parameter to create a nested subfolder inside an
        existing parent folder.

        **Required permission:** WRITER or higher

        **Folder features:**

        - Organize records hierarchically
        - Support nested subfolders, up to 20 levels deep
        - Inherit parent KB permissions

        **Naming rules:**

        - Whitespace around the name is removed first; then 1–255 characters
        - A name holding an HTML tag, a `javascript:` URL or an inline event handler is
          refused with `400` before authentication; one holding a printf-style format
          specifier (`%s`, `%x`, `%n`, `%p`) is refused with `400` by the gateway controller
        - Spaces and special characters allowed
        - A name already used by a folder in the same parent is refused with `409`, ignoring
          case (`Reports` and `rEPORTS` clash). A file of the same name, or a folder of the
          same name under another parent, does not clash.

        **Request:** only `folderName` and the `folderId` query parameter are read; other body
        fields and query parameters are ignored, except a `folderId`, `parentId` or
        `parent_id` in the body and a `parentId` or `parent_id` query parameter, which are
        refused with `400`.

        **Access:** a caller with no role on the knowledge base gets `404`
        (`Knowledge base <kbId> not found`), a `READER` gets `403`.

        **Response:** Returns `id` and `name` for the created folder.
      operationId: createFolder
      security:
      - bearerAuth: []
      - oauth2:
        - kb:write
      parameters:
      - name: kbId
        in: path
        required: true
        description: Knowledge base ID
        schema:
          type: string
          format: uuid
      - name: folderId
        in: query
        required: false
        description: |
          Parent folder ID. Omit to create at the knowledge base root. An id that is not a
          folder of this knowledge base (unknown, or a file) is answered `404`.
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              type: object
              properties:
                folderName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]))[\s\S]*?\S
                  description: |
                    Name of the folder. Whitespace around it is removed first, so a name made
                    only of whitespace is refused as empty.
                    It cannot contain `/` or `\`, which folder paths use as separators.
                  example: Project Documents
              required:
              - folderName
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                folderName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]))[\s\S]*?\S
                  description: |
                    Name of the folder. Whitespace around it is removed first, so a name made
                    only of whitespace is refused as empty.
                    It cannot contain `/` or `\`, which folder paths use as separators.
                  example: Project Documents
              required:
              - folderName
      responses:
        '200':
          description: Folder created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderCreateResponseSchema'
        '400':
          description: |
            Invalid request. Possible reasons:

            - `folderName` missing, `null`, not a string, empty or only whitespace, or longer
              than 255 characters; `kbId` not a UUID; `folderId` empty (`VALIDATION_ERROR`)
            - A `folderId`, `parentId` or `parent_id` in the body, or a `parentId` or `parent_id`
              query parameter (`VALIDATION_ERROR`, `To create a subfolder, use the subfolder route.`):
              use `POST /knowledgeBase/{kbId}/folder/{folderId}/subfolder` instead
            - `folderName` contains an HTML tag, a `javascript:` URL or an inline event handler
              (`HTTP_BAD_REQUEST`). This check runs before authentication.
            - `folderName` contains a format specifier (`HTTP_BAD_REQUEST`)
            - `folderName` contains `/` or `\` (`VALIDATION_ERROR`, `Folder names cannot contain "/" or "\".`)
            - The parent is already 20 levels deep
              (`Folders can be nested at most 20 levels deep. ...`)
            - `kbId` holds a character that cannot stand in a URL path segment (`/`, `\`, `?`,
              `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Possible reasons:

            - OAuth token lacks the `kb:write` scope
            - User is `READER` (`... OWNER or WRITER role required, but your role is: READER.`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            - `Knowledge base <kbId> not found`: unknown knowledge base, or the caller holds no
              role on it
            - `Parent folder <folderId> not found in KB <kbId>`: `folderId` is not a folder of
              this knowledge base (unknown id, or a file)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Conflict. Possible reasons:

            - A folder with this name already exists at the knowledge base root or within the parent folder
            - The parent folder is in Recently deleted; restore it first, or choose another folder

            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while creating folder.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/{kbId}/folder/{folderId}/subfolder:
    post:
      tags:
      - Knowledge Base
      summary: Create subfolder
      description: |
        Create a nested subfolder inside an existing parent folder, named by the `folderId`
        path parameter. It runs the same validator and handler as
        `POST /knowledgeBase/{kbId}/folder`. A `folderId` query parameter is still read: one
        that names a different folder than the path is refused with `400`.

        **Required permission:** WRITER or higher

        **Folder features:**

        - Organize records hierarchically
        - Support nested subfolders, up to 20 levels deep
        - Inherit parent KB permissions

        **Naming rules:**

        - Whitespace around the name is removed first; then 1–255 characters
        - A name holding an HTML tag, a `javascript:` URL or an inline event handler is
          refused with `400` before authentication; one holding a printf-style format
          specifier (`%s`, `%x`, `%n`, `%p`) is refused with `400` by the gateway controller
        - Spaces and special characters allowed
        - A name already used by a folder in the same parent is refused with `409`, ignoring
          case (`Reports` and `rEPORTS` clash). A file of the same name, or a folder of the
          same name under another parent, does not clash.

        **Request:** only `folderName` and the `folderId` query parameter are read; other body
        fields and query parameters are ignored, except a `folderId`, `parentId` or
        `parent_id` in the body and a `parentId` or `parent_id` query parameter, which are
        refused with `400`.

        **Access:** a caller with no role on the knowledge base gets `404`
        (`Knowledge base <kbId> not found`), a `READER` gets `403`.

        **Response:** Returns `id` and `name` for the created folder.
      operationId: createSubfolder
      security:
      - bearerAuth: []
      - oauth2:
        - kb:write
      parameters:
      - name: kbId
        in: path
        required: true
        description: Knowledge base ID
        schema:
          type: string
          format: uuid
      - name: folderId
        in: path
        required: true
        description: |
          Parent folder ID. An id that is not a folder of this knowledge base (unknown, or a
          file) is answered `404`.
        schema:
          type: string
          format: uuid
      - name: folderId
        in: query
        required: false
        description: |
          Optional. When sent, it must equal the `folderId` path parameter (`Conflicting
          folderId in path and query parameters`).
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              type: object
              properties:
                folderName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]))[\s\S]*?\S
                  description: |
                    Name of the folder. Whitespace around it is removed first, so a name made
                    only of whitespace is refused as empty.
                    It cannot contain `/` or `\`, which folder paths use as separators.
                  example: Project Documents
              required:
              - folderName
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                folderName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]))[\s\S]*?\S
                  description: |
                    Name of the folder. Whitespace around it is removed first, so a name made
                    only of whitespace is refused as empty.
                    It cannot contain `/` or `\`, which folder paths use as separators.
                  example: Project Documents
              required:
              - folderName
      responses:
        '200':
          description: Folder created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderCreateResponseSchema'
        '400':
          description: |
            Invalid request. Possible reasons:

            - `folderName` missing, `null`, not a string, empty or only whitespace, or longer
              than 255 characters; `kbId` or the path `folderId` not a UUID; the query `folderId`
              empty (`VALIDATION_ERROR`)
            - The query `folderId` names a different folder than the path (`HTTP_BAD_REQUEST`,
              `Conflicting folderId in path and query parameters`)
            - A `folderId`, `parentId` or `parent_id` in the body, or a `parentId` or `parent_id`
              query parameter (`VALIDATION_ERROR`, `To create a subfolder, use the subfolder route.`):
              name the parent in the path only
            - `folderName` contains an HTML tag, a `javascript:` URL or an inline event handler
              (`HTTP_BAD_REQUEST`). This check runs before authentication.
            - `folderName` contains a format specifier (`HTTP_BAD_REQUEST`)
            - `folderName` contains `/` or `\` (`VALIDATION_ERROR`, `Folder names cannot contain "/" or "\".`)
            - The parent is already 20 levels deep
              (`Folders can be nested at most 20 levels deep. ...`)
            - `kbId` or `folderId` holds a character that cannot stand in a URL path segment (`/`, `\`, `?`,
              `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Possible reasons:

            - OAuth token lacks the `kb:write` scope
            - User is `READER` (`... OWNER or WRITER role required, but your role is: READER.`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            - `Knowledge base <kbId> not found`: unknown knowledge base, or the caller holds no
              role on it
            - `Parent folder <folderId> not found in KB <kbId>`: `folderId` is not a folder of
              this knowledge base (unknown id, or a file)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Conflict. Possible reasons:

            - A folder with this name already exists at the knowledge base root or within the parent folder
            - The parent folder is in Recently deleted; restore it first, or choose another folder

            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while creating folder.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/{kbId}/folder/{folderId}:
    put:
      tags:
      - Knowledge Base
      summary: Update folder
      description: |
        Rename a folder, at the root or nested.

        **Required permission:** WRITER or higher. A `READER` gets `403`; a caller with no
        role on the knowledge base gets `404` (`Knowledge base not found`).

        **Naming rules:** the same as for creating a folder. Whitespace around the name is
        removed first; HTML is refused with `400` before authentication and a printf-style
        format specifier with `400` by the gateway controller. A name already used by another
        folder in the same parent is refused with `409`, ignoring case; renaming a folder to
        its own name, or to the name of a file, is allowed.

        **Request:** `kbId` and `folderId` are only checked to be non-empty (an id that is not
        a UUID is looked up and answered `404`). Only `folderName` is read; other body fields
        and any query parameter are ignored.
      operationId: updateFolder
      security:
      - bearerAuth: []
      - oauth2:
        - kb:write
      parameters:
      - name: kbId
        in: path
        required: true
        schema:
          type: string
      - name: folderId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              type: object
              properties:
                folderName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]))[\s\S]*?\S
                  description: |
                    New name of the folder. Whitespace around it is removed first, so a name
                    made only of whitespace is refused as empty.
                    It cannot contain `/` or `\`, which folder paths use as separators.
              required:
              - folderName
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                folderName:
                  type: string
                  minLength: 1
                  maxLength: 255
                  pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]))[\s\S]*?\S
                  description: |
                    New name of the folder. Whitespace around it is removed first, so a name
                    made only of whitespace is refused as empty.
                    It cannot contain `/` or `\`, which folder paths use as separators.
              required:
              - folderName
      responses:
        '200':
          description: Folder updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderUpdateResponseSchema'
        '400':
          description: |
            Invalid request. Possible reasons:

            - `folderName` missing, `null`, not a string, empty or only whitespace, or longer
              than 255 characters (`VALIDATION_ERROR`)
            - `folderName` contains an HTML tag, a `javascript:` URL or an inline event handler
              (`HTTP_BAD_REQUEST`). This check runs before authentication.
            - `folderName` contains a format specifier (`HTTP_BAD_REQUEST`)
            - `folderName` contains `/` or `\` (`VALIDATION_ERROR`, `Folder names cannot contain "/" or "\".`)
            - `kbId` or `folderId` holds a character that cannot stand in a URL path segment (`/`, `\`, `?`,
              `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Possible reasons:

            - OAuth token lacks the `kb:write` scope
            - User is `READER` (`You do not have permission to perform this action on this knowledge base`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            - `Knowledge base not found`: unknown knowledge base (any id, UUID or not), or the
              caller holds no role on it
            - `Folder not found in knowledge base`: `folderId` is not a folder of this knowledge
              base (unknown id, or a file)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Another folder in the same parent already has this name, ignoring case
            (`Folder '<name>' already exists in collection root` at the root,
            `... already exists in this folder` in a folder).

            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while updating folder.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Knowledge Base
      summary: Delete folder
      description: |
        Delete a folder and all its contents.

        **Required permission:** WRITER or higher. A `READER` gets `403`; a caller with no
        role on the knowledge base gets `404`.

        **Cascade delete:**

        All subfolders and records within are deleted for good, unless "Move Deleted Records
        to the Trash" (Labs flag `ENABLE_SOFT_DELETE`) is on: then they all go to the trash and
        can be brought back with `POST /knowledgeBase/record/{folderId}/restore`. The response
        is the same in both cases. Known gap: while in the trash, the folder is still listed
        in `folders` by `GET /knowledgeBase/{kbId}`, although its records answer `404`.

        **Request:** `kbId` and `folderId` are only checked to be non-empty; any query string
        or body is ignored.
      operationId: deleteFolder
      security:
      - bearerAuth: []
      - oauth2:
        - kb:delete
      parameters:
      - name: kbId
        in: path
        required: true
        schema:
          type: string
      - name: folderId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Folder deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FolderDeleteResponseSchema'
        '400':
          description: |
            `kbId` or `folderId` holds a character that cannot stand in a URL path segment (`/`, `\`, `?`,
              `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Possible reasons:

            - OAuth token lacks the `kb:delete` scope
            - User is `READER` (`User lacks permission to delete folder`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            - `Knowledge base not found`: unknown knowledge base (any id, UUID or not), or the
              caller holds no role on it
            - `Folder not found in knowledge base`: `folderId` is not a folder of this knowledge
              base (unknown id, already deleted, or a file)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while deleting the folder.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/{kbId}/upload:
    post:
      tags:
      - Knowledge Base
      summary: Upload files to knowledge base or folder
      description: |
        Upload one or more files to a knowledge base root or to a specific folder.

        **Overview**

        Batch upload multiple files in a single request. Each file becomes a new record with automatic content indexing.
        Omit the `folderId` query parameter to upload to the KB root; include it to upload into that folder.

        **Upload Limits**

        - **Max files per request:** 1000
        - **Default max file size:** 30MB (configurable via platform settings)
        - Use `GET /knowledgeBase/limits` to check current limits

        **Supported File Types**

        Documents (PDF, DOCX, DOC, XLS, XLSX, PPT, PPTX, TXT, CSV, MD), Images (PNG, JPG, JPEG, SVG, WebP), Web (HTML, HTM), and Google Workspace formats.

        **File Metadata**

        Use `files_metadata` to provide additional info like file paths and last modified timestamps.
        A path with folders (`docs/2026/a.txt`) creates those folders, as a folder upload does.

        **Rejected files**

        A file whose extension is not supported, or that is larger than the size limit, does
        not fail the request: it is reported as a `file:failed` event (`reason`
        `UNSUPPORTED_TYPE` or `EXCEEDS_SIZE_LIMIT`, `stage: upload`) and the other files go on.
        A file whose name is already used in the same place fails the same way with `reason`
        `DUPLICATE_NAME` and `stage: index`. The request still answers `200` when every file
        failed. There is no `413`.

        **Ignored fields**

        `recordName`, `recordType` and `origin` are validated (non-empty, and `recordName` is
        checked for HTML and format specifiers) but do not affect the records: each record is
        named after its file, with origin `UPLOAD` and type `FILE`. Other fields and unknown
        query parameters are ignored; `rejectedFiles` and `fileBuffers` are set by the gateway
        itself, so a value sent for them is replaced.

        **Access**

        `OWNER` and `WRITER` may upload. A `READER` gets `403`; a caller with no role on the
        knowledge base gets `404`. Only a multipart body is read: a JSON body has no files and
        is refused with `400`.

        **Versioning**

        Set `isVersioned: true` to enable version tracking for uploaded files.

        **Streaming response**

        This endpoint responds with `Content-Type: text/event-stream`.
        The upload and its per-file progress are a single request: the body streams
        a `file:succeeded` or `file:failed` event per file
        (including files rejected up front for size/type), followed by a final
        `done` summary, then closes. See the
        `UploadStreamSSEEvent` schema for the event/payload contract.
      operationId: uploadRecords
      security:
      - bearerAuth: []
      - oauth2:
        - kb:upload
        - kb:read
      parameters:
      - name: kbId
        in: path
        required: true
        description: Knowledge base ID (UUID)
        schema:
          type: string
          format: uuid
      - name: folderId
        in: query
        required: false
        description: |
          Target folder ID. Omit to upload to the KB root. A folder that is not in this
          knowledge base is answered `404`.
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        description: Request payload
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: Files to upload (max 1000)
                files_metadata:
                  type: array
                  minItems: 1
                  description: |
                    JSON text: an array with one entry per file, in the order of the `files`
                    parts, each `{file_path, last_modified}` with `last_modified` in epoch
                    milliseconds (a number, not a date string). A file without an entry is
                    named after its part and timed at the upload. Text that is not JSON, or an
                    array whose length differs from the number of files, is refused with `400`
                    (`HTTP_BAD_REQUEST`); an entry without a string `file_path` or a numeric
                    `last_modified` is refused with `400` (`VALIDATION_ERROR`).
                  items:
                    type: object
                    required:
                    - file_path
                    - last_modified
                    properties:
                      file_path:
                        type: string
                      last_modified:
                        type: number
                  example: '[{"file_path":"docs/report.pdf","last_modified":1705314600000}]'
                isVersioned:
                  type: string
                  enum:
                  - 'true'
                  - 'false'
                  - '1'
                  - '0'
                  - ''
                  default: 'true'
                  description: |
                    Enable version tracking. `true`/`1` and `false`/`0`/empty are read as
                    booleans; any other text is answered `500` (the validator throws a plain
                    error).
                recordName:
                  type: string
                  minLength: 1
                  pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]))
                  description: Validated, then ignored (records are named after their files).
                origin:
                  type: string
                  minLength: 1
                  description: Validated, then ignored (records get origin `UPLOAD`).
                recordType:
                  type: string
                  minLength: 1
                  default: FILE
                  description: Validated, then ignored (records get type `FILE`).
              required:
              - files
      responses:
        '200':
          description: |
            SSE stream (`text/event-stream`) of per-file upload outcomes. The
            stream emits `file:succeeded` / `file:failed` per file and a final
            `done` summary, then closes. See `UploadStreamSSEEvent`.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/UploadStreamSSEEvent'
        '400':
          description: |
            - `kbId` not a UUID, `folderId` empty, `recordName`/`recordType`/`origin` empty, or a
              `files_metadata` entry without a string `file_path` or a numeric `last_modified`
              (`VALIDATION_ERROR`)
            - No `files` part (`No files available for processing`), files sent under another
              field name (`The files weren't sent the way this page expects. ...`), more than
              1000 files, or more than 1 GB in total (`HTTP_BAD_REQUEST`)
            - `files_metadata` is not JSON (`Invalid files_metadata format. Expected JSON array.`)
              or has another length than the files (`Metadata count mismatch: ...`)
            - `recordName` holds a format specifier, or any field holds HTML (the HTML check runs
              before authentication)
            - `kbId` holds a character that cannot stand in a URL path segment (`/`, `\`, `?`,
              `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            - OAuth token lacks the `kb:upload` scope (`Insufficient scope. Required: kb:upload`)
            - OAuth token holds `kb:upload` but not `kb:read`: the knowledge base lookup that
              precedes the upload needs `kb:read`, so the caller gets
              `You do not have permission to upload to this knowledge base`
            - Caller is `READER`: `You do not have permission to upload to this knowledge base`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            - `Knowledge base <kbId> not found`: unknown knowledge base, or the caller holds no
              role on it
            - `Folder <folderId> was not found in knowledge base '<name>' (<kbId>). ...`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            The `folderId` folder is in Recently deleted (`'<folder>' is in Recently deleted, so you
            can't upload files to it. Restore it first, or choose another folder.`), answered before
            the stream starts. Restore the folder first, or choose another folder.

            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many upload requests, or too many concurrent uploads for this user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Failed to verify knowledge base or folder access.

            Also answered for an `isVersioned` that is not `true`, `false`, `1`, `0` or empty.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/limits:
    get:
      tags:
      - Knowledge Base
      summary: Get knowledge base upload limits
      description: |
        Retrieve current upload constraints for the organization.

        **Use case:** Call this before uploads to validate file sizes on the client
        side and display appropriate limits to users.

        `maxFilesPerRequest` is a fixed 1000. `maxFileSizeBytes` is the organization's
        `fileUploadMaxSizeBytes` platform setting, read on every call (30 MB when the
        setting cannot be read). Any signed-in member gets the same values; no knowledge
        base role is needed.

        **Request:** there is no validator and nothing from the request is read; any query
        string is ignored.
      operationId: getUploadLimits
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      responses:
        '200':
          description: Upload limits retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadLimitsResponseSchema'
        '400':
          $ref: '#/components/responses/XssRejected'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - the OAuth token lacks the `kb:read` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/reindex/record/{recordId}:
    post:
      tags:
      - Knowledge Base
      summary: Reindex single record
      description: |
        Trigger reindexing for a specific record.

        **Overview:**

        Reprocesses the record's content to update search indexes and AI embeddings. Useful after content changes or to fix indexing failures.

        **Depth parameter:**

        Controls processing depth for complex documents (`-1` for full depth, `0`–`100` for limited).

        **Status filters:**

        Optional `statusFilters` array limits reindex to records in matching indexing states
        (e.g. `FAILED`, `AUTO_INDEX_OFF`, `PASSWORD_PROTECTED`). Any string is accepted.

        **Access:** any role on the record's knowledge base may reindex it, `READER` included.
        For a connector record, read access to the record is enough. A record of a disabled
        connector is refused with `409`, a record in the trash with `400`.

        **Request:** only `depth` and `statusFilters` are read; other body fields (`force`
        included) and any query parameter are ignored. The body is optional.
      operationId: reindexRecord
      security:
      - bearerAuth: []
      - oauth2:
        - kb:write
      parameters:
      - name: recordId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReindexRecordRequestBody'
      responses:
        '200':
          description: Reindexing triggered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reIndexRecordResponseSchema'
        '400':
          description: |
            - `depth` not a whole number from -1 to 100, `statusFilters` not a list of strings, or
              a body that is not an object (`VALIDATION_ERROR`)
            - The record is in the trash: `Cannot reindex deleted record`
            - The record belongs to a GitHub/GitLab repository-wide code graph and cannot be
              reindexed on its own. Reindex the whole repository with
              `POST /knowledgeBase/reindex/record-group/{recordGroupId}`, or run a connector
              sync to pick up changes from the repository.
            - The record's origin is neither an upload nor a connector
            - `recordId` holds a character that cannot stand in a URL path segment (`/`, `\`, `?`,
              `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            - OAuth token is missing the required kb:write scope
            - The caller holds no role on the record's knowledge base:
              `Insufficient KB permissions. Required: OWNER, WRITER, READER` (for a connector
              record: `Insufficient permissions. Required: OWNER, WRITER, READER`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            `Record not found: <recordId>`: no record has this id (a knowledge base id is not a
            record id). Also `Knowledge base context not found for record <recordId>`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Conflict — the connector instance for this record is disabled
            (`The connector '<name>' is currently disabled. Enable it from Connector Settings and try again.`),
            or is locked by a sync or another operation in progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while reindexing the record.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/reindex/record-group/{recordGroupId}:
    post:
      tags:
      - Knowledge Base
      summary: Reindex record group
      description: |
        Trigger reindexing for all records in a record group.

        **Overview:**

        Batch reindex operation for a connector's container (a drive, a space, a channel, a
        crawled site). Record groups are written by connector syncs only: a knowledge base id
        or a knowledge base folder id is not a record group and is answered `404` (reindex
        those with `POST /knowledgeBase/reindex/record/{recordId}` and a depth).

        **Status filters:**

        Optional `statusFilters` limit which child records are queued (e.g. failed-only or
        manual-indexing). Any string is accepted.

        **Access:** the caller needs access to the record group (an organization-wide
        connector gives it to every member; a personal one only to its owner); without it the
        answer is `403`. A record group of a disabled connector is refused with `409`.

        **Request:** only `depth` and `statusFilters` are read; other body fields (`force`
        included) and any query parameter are ignored. The body is optional.
      operationId: reindexRecordGroup
      security:
      - bearerAuth: []
      - oauth2:
        - kb:write
      parameters:
      - name: recordGroupId
        in: path
        required: true
        description: Record group ID (from a connector sync; not a knowledge base or folder id)
        schema:
          type: string
      requestBody:
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReindexRecordGroupRequestBody'
      responses:
        '200':
          description: Reindexing triggered for all records in group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReIndexRecordGroupResponseSchema'
        '400':
          description: |
            - `depth` not a whole number from -1 to 100, `statusFilters` not a list of strings, or
              a body that is not an object (`VALIDATION_ERROR`)
            - The record group has no connector
            - `recordGroupId` holds a character that cannot stand in a URL path segment (`/`, `\`, `?`,
              `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            - OAuth token is missing the required kb:write scope
            - The caller has no access to the record group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            `Record group not found: <recordGroupId>`: no record group has this id (a knowledge
            base id or folder id is not a record group id).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Conflict - the connector instance is disabled
            (`The connector '<name>' is currently disabled. Enable it from Connector Settings and try again.`),
            or is locked by a sync or another operation in progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while reindexing the record group.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/{kbId}/record/{recordId}/move:
    put:
      tags:
      - Knowledge Base
      summary: Move record to another location
      description: |
        Move a file or folder record to a different location within the same knowledge base.

        Set `newParentId` to a folder ID to move the record into that folder, or `null` (or an
        empty string) to move it to the knowledge base root. A folder moves with everything in
        it. Moving a record to where it already is answers `200` with the same body.

        **Required Permission:** OWNER or WRITER. A `READER` gets `403`; a caller with no role
        on the knowledge base gets `404` (`Knowledge base not found`).

        **Request:** only `newParentId` is read; other body fields and any query parameter
        are ignored.
      operationId: moveRecord
      security:
      - bearerAuth: []
      - oauth2:
        - kb:write
      parameters:
      - name: kbId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Knowledge base UUID
      - name: recordId
        in: path
        required: true
        schema:
          type: string
          minLength: 1
        description: |
          Record identifier (file or folder). A record that is not in this knowledge base
          (unknown, or in another one) is answered `404`.
      requestBody:
        required: true
        description: Target location for the record
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeBaseMoveRecordRequestBody'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/KnowledgeBaseMoveRecordRequestBody'
      responses:
        '200':
          description: Record moved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseMoveRecordResponse'
        '400':
          description: |
            Invalid request. Possible reasons:

            - `newParentId` missing or not a string or `null`, or `kbId` not a UUID
              (`VALIDATION_ERROR`)
            - `kbId` or `recordId` holds a character that cannot stand in a URL path segment (`/`, `\`, `?`,
              `#`, `%`, a control character) or is `.` or `..` (`HTTP_BAD_REQUEST`)
            - `Cannot move a folder into itself`
            - `Cannot move a folder into one of its own sub-folders (circular reference)`
            - The move would nest folders more than 20 levels deep
              (`Folders can be nested at most 20 levels deep. ...`)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden. Possible reasons:

            - OAuth token lacks the `kb:write` scope
            - User is `READER` (`You do not have permission to perform this action on this knowledge base`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Not found. Possible reasons:

            - `Knowledge base not found`: the knowledge base does not exist, or the caller holds
              no role on it
            - `Record <recordId> not found in KB <kbId>`: the record is unknown or belongs to
              another knowledge base
            - `Target folder <newParentId> not found in KB <kbId>`: the target is unknown or is a
              file
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Conflict. Possible reasons:

            - The target already holds a record of the same name: `Folder '<name>' already exists
              in this folder` for a folder, `A file named '<name>' already exists in this folder`
              for a file (the name is given without its extension). At the root the location reads
              `collection root` or `this location`.
            - The target folder is in Recently deleted: `'<folder>' is in Recently deleted, so you
              can't move items into it. Restore it first, or choose another folder.` This is checked
              before the already-there check, so it is answered even when the item is already in
              that folder.

            The knowledge base is being deleted (`error.code` is `HTTP_KB_BEING_DELETED`): it can no longer be changed. Reads still work and show `status: DELETING`; retry the delete instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while moving record.


            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /knowledgeBase/knowledge-hub/nodes:
    get:
      deprecated: true
      x-speakeasy-deprecation-message: Use the Knowledge Base API instead. This grouping will be removed in a future release
      tags:
      - Knowledge Base
      - Knowledge Hub
      summary: Get knowledge hub root nodes
      description: |
        Returns root-level nodes (connector apps and Collection apps) or, when
        filters or search are applied, a flat list of matching nodes across the
        entire knowledge hub tree.

        **Overview**

        The Knowledge Hub provides a unified view across all knowledge sources:
        - **Collection** — locally uploaded knowledge bases (`origin: COLLECTION`)
        - **Connector app** — external connector instances such as Google Drive,
          Slack, Confluence, Jira (`origin: CONNECTOR`)

        Use this endpoint to build file-browser UIs and sidebar navigation trees.

        **Browsing vs. searching**

        When no filters or search query are provided, only top-level app nodes
        are returned. Adding `nodeTypes`, `q`, or other filter params triggers a
        search across the full tree, returning matching nodes regardless of depth.

        For children of a specific node, use
        `GET /knowledgeBase/knowledge-hub/nodes/{parentType}/{parentId}`.

        **Pagination and sorting**

        Results are always paginated. Default sort is `updatedAt` descending.
        The `pagination` object in the response contains `hasNext` / `hasPrev`
        flags suitable for infinite-scroll or page-based navigation.

        **Expanding the response**

        Use the `include` parameter to request additional sections:
        - `availableFilters` — adds `filters.available` with all filter options
        - `counts` — adds a `counts` summary broken down by node type
        - `breadcrumbs` — adds the breadcrumb trail (empty at root level)
        - `permissions` — adds the caller's permission flags

        **A connected app with a limit**

        A token that may see only some sources pages and counts only what
        its limit lets it see:
        - Limited to whole sources (apps or collections) only: the listing
          and the search cover those, with exact totals and counts.
        - Limited to any spaces, folders or files, alone or beside whole
          sources: the listing returns each whole source, space (record
          group), folder and file the limit names, one item each, to open
          by its `id`. `totalItems` counts those items, not what is inside
          them. A search reads
          forward only (`prevCursor` is always null), and takes a `page`
          number up to 5; for later pages, send `nextCursor`. Its `totalItems` counts
          the matches found so far and can grow from page to page; it is
          final once `hasNext` is false. `counts` is returned only when the
          whole result fits in the first page read, and is `null` otherwise.
        - An item can sit in a folder the limit leaves out, as a file the
          limit names does. Its `parentId` and `parent` are then `null`: the
          item is returned, and the folder above it is not named.
        - A `nextCursor` or `prevCursor` belongs to the limit it was read
          under. A token with a different limit that sends it gets a `400`;
          start that listing again without a cursor.

        **Access control**

        Requires a valid bearer token. For OAuth tokens the `kb:read` scope
        must be present; regular JWT bearer tokens pass through without scope
        enforcement. Only nodes the caller can access are listed.

        **Request checking**

        This route has no request validator of its own; the query is passed on and
        checked by the connector service. Query parameters not listed here are
        ignored. A wrong type for `page`, `limit`, `onlyContainers` or `flattened`
        (or `page` below 1 or `limit` outside 1-200, or either sent more than once) is answered
        `422`; a refused filter value is answered `400`.
      operationId: getKnowledgeHubRootNodes
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      parameters:
      - name: onlyContainers
        in: query
        required: false
        description: |
          When `true`, only nodes that have children are returned (useful for
          building sidebar / tree navigation). Leaf nodes are excluded.
          `yes`/`no`, `on`/`off` and `1`/`0` are read as booleans too; anything
          else is answered `422`.
        schema:
          type: boolean
          default: false
      - name: page
        in: query
        required: false
        description: |
          Page number (1-indexed, at most 50). Combined with `limit` to paginate results.
          Prefer `cursor`: a page number is reached by reading the pages before it.
          A search by a connected app whose limit names any spaces, folders or files
          takes a page number of at most 5; for later pages, send `nextCursor`.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: cursor
        in: query
        required: false
        description: |
          Opaque cursor from `pagination.nextCursor` or `pagination.prevCursor` of a previous
          response. It decides the listing mode, parent, filters and sort. `include` and
          `limit` come from this request. A next cursor returns the following page, and a previous
          cursor returns the page before. A cursor whose parent disagrees with the URL, or
          that was issued for another user, is refused with 400.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: |
          Maximum number of items to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: sortBy
        in: query
        required: false
        description: |
          Field to sort results by. Omitted → default `updatedAt`.
          Any other value is answered `400` ("Invalid sort_by: ...").
        schema:
          type: string
          enum:
          - name
          - createdAt
          - updatedAt
          - size
          - type
          default: updatedAt
      - name: sortOrder
        in: query
        required: false
        description: |
          Sort direction. Omitted → default `desc`. Read case-insensitively;
          any other value is answered `400` ("Invalid sort_order: ...").
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: q
        in: query
        required: false
        description: |
          Full-text search query. Must be between 2 and 500 characters
          (inclusive) after surrounding whitespace is removed, otherwise `400`.
          When provided, the endpoint searches across the entire
          node tree regardless of the current browse level.
          A repeated `q` is joined with commas into one query, and a `q` sent as an object
          (`q[a]=b`) is refused with `400` ("Search query must be text").
        schema:
          type: string
          minLength: 2
          maxLength: 500
        example: quarterly report
      - name: nodeTypes
        in: query
        required: false
        description: |
          Comma-separated list of node types to include. An unknown value is
          answered `400` ("Invalid node_types value(s): ..."). Maximum 100 items.

          Valid values: `folder`, `app`, `recordGroup`, `record`
        schema:
          type: string
        example: app,recordGroup
      - name: recordTypes
        in: query
        required: false
        description: |
          Comma-separated list of record types to include. An unknown value is
          answered `400` ("Invalid record_types value(s): ..."). Maximum 100 items.

          Valid values: `FILE`, `DRIVE`, `WEBPAGE`, `DATABASE`, `DATASOURCE`,
          `MESSAGE`, `MAIL`, `GROUP_MAIL`, `TICKET`, `COMMENT`,
          `INLINE_COMMENT`, `CONFLUENCE_PAGE`, `CONFLUENCE_BLOGPOST`,
          `SHAREPOINT_PAGE`, `SHAREPOINT_LIST`, `SHAREPOINT_LIST_ITEM`,
          `SHAREPOINT_DOCUMENT_LIBRARY`, `LINK`, `PROJECT`, `PULL_REQUEST`,
          `MEETING`, `PRODUCT`, `DEAL`, `CASE`, `TASK`, `ARTIFACT`,
          `CODE_FILE`, `SQL_TABLE`, `SQL_VIEW`, `OTHERS`
        schema:
          type: string
        example: FILE,CONFLUENCE_PAGE
      - name: origins
        in: query
        required: false
        description: |
          Comma-separated list of origin types to include. An unknown value is
          answered `400` ("Invalid origins value(s): ..."). Maximum 100 items.

          Valid values: `COLLECTION`, `CONNECTOR`
        schema:
          type: string
        example: CONNECTOR
      - name: connectorIds
        in: query
        required: false
        description: |
          Comma-separated list of connector instance IDs (UUIDs) to filter by.
          Maximum 100 items. No enum validation — any string is accepted, but
          non-existent IDs simply yield zero results.
        schema:
          type: string
        example: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
      - name: indexingStatus
        in: query
        required: false
        description: |
          Comma-separated list of indexing statuses to include. An unknown value
          is answered `400` ("Invalid indexing_status value(s): ..."). Maximum 100 items.

          Valid values: `NOT_STARTED`, `PAUSED`, `IN_PROGRESS`, `COMPLETED`,
          `FAILED`, `FILE_TYPE_NOT_SUPPORTED`, `AUTO_INDEX_OFF`, `EMPTY`,
          `ENABLE_MULTIMODAL_MODELS`, `QUEUED`, `SKIPPED`, `PASSWORD_PROTECTED`
        schema:
          type: string
        example: COMPLETED,FAILED
      - name: createdAt
        in: query
        required: false
        description: |
          Created-date range filter. Format: `gte:<epochMs>,lte:<epochMs>`.
          Both bounds are optional (you may send just `gte:...` or just
          `lte:...`). Timestamps must be in the range 0 to 9999999999999 and
          `gte` must be less than or equal to `lte` when both are present;
          a bound that is not a whole number, is out of range, or an inverted
          range is answered `400`. A value with no `gte:`/`lte:` part is ignored.
        schema:
          type: string
        example: gte:1700000000000,lte:1710000000000
      - name: updatedAt
        in: query
        required: false
        description: |
          Updated-date range filter. Same format and constraints as `createdAt`.
        schema:
          type: string
        example: gte:1700000000000,lte:1710000000000
      - name: size
        in: query
        required: false
        description: |
          File-size range filter in bytes. Format: `gte:<bytes>,lte:<bytes>`.
          Both bounds are optional. Values must be non-negative and at most
          1099511627776 (1 TB). `gte` must be less than or equal to `lte`
          when both are present.
        schema:
          type: string
        example: gte:0,lte:10485760
      - name: flattened
        in: query
        required: false
        description: |
          Force flattened/recursive search (`true`) or direct top-level
          listing (`false`). When omitted, it's computed from whether any
          of `q`, `nodeTypes`, `recordTypes`, `origins`, `connectorIds`,
          `indexingStatus`, `createdAt`, `updatedAt`, or `size` are present —
          if any are, results are flattened automatically; otherwise only
          top-level nodes are returned.
        schema:
          type: boolean
      - name: include
        in: query
        required: false
        description: |
          Comma-separated list of additional response sections to include.
          An unknown value is answered `400` ("Invalid include value(s): ...").
          Maximum 100 items.

          Valid values: `breadcrumbs`, `counts`, `availableFilters`, `permissions`
        schema:
          type: string
        example: availableFilters,counts
      responses:
        '200':
          description: |
            Paginated list of root hub nodes (connector apps and Collections).
            HTTP 200 returns `success: true` and `error: null`. Field-level detail
            and required keys are defined on `KnowledgeHubNodesResponse`.

            Use `include` for optional sections: `availableFilters`, `counts`,
            `permissions` — each stays JSON `null` when not asked for.
            `breadcrumbs` stays `null` at this route (no parent in the path),
            even if `include` lists `breadcrumbs`; use the child route for trails.
            `id`, `currentNode`, and `parentNode` are `null` here.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeHubNodesResponse'
              examples:
                root_apps:
                  summary: Root-level apps with availableFilters included
                  value:
                    success: true
                    error: null
                    id: null
                    currentNode: null
                    parentNode: null
                    items:
                    - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      name: My Knowledge Base
                      nodeType: app
                      parentId: null
                      origin: UPLOAD
                      connector: null
                      recordType: null
                      recordGroupType: null
                      indexingStatus: null
                      reason: null
                      createdAt: 1700000000000
                      updatedAt: 1710000000000
                      sizeInBytes: null
                      mimeType: null
                      extension: null
                      webUrl: /app/a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      hasChildren: true
                      previewRenderable: null
                      permission: null
                      sharingStatus: workspace
                      isInternal: false
                      isPlaceholder: false
                    - id: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
                      name: Google Drive
                      nodeType: app
                      parentId: null
                      origin: CONNECTOR
                      connector: drive
                      recordType: null
                      recordGroupType: null
                      indexingStatus: null
                      reason: null
                      createdAt: 1700000000000
                      updatedAt: 1709000000000
                      sizeInBytes: null
                      mimeType: null
                      extension: null
                      webUrl: /app/f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
                      hasChildren: true
                      previewRenderable: null
                      permission: null
                      sharingStatus: null
                      isInternal: false
                      isPlaceholder: false
                    pagination:
                      page: 1
                      limit: 20
                      totalItems: 2
                      totalPages: 1
                      hasNext: false
                      hasPrev: false
                    filters:
                      applied:
                        q: null
                        nodeTypes: null
                        recordTypes: null
                        origins: null
                        connectorIds: null
                        indexingStatus: null
                        createdAt: null
                        updatedAt: null
                        size: null
                        sortBy: updatedAt
                        sortOrder: desc
                      available:
                        nodeTypes:
                        - id: app
                          label: Apps
                        - id: recordGroup
                          label: Record Groups
                        recordTypes: []
                        origins:
                        - id: COLLECTION
                          label: Collection
                        - id: CONNECTOR
                          label: Connector
                        connectors:
                        - id: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
                          label: Google Drive
                          connectorType: drive
                        indexingStatus: []
                        sortBy:
                        - id: name
                          label: Name
                        - id: updatedAt
                          label: Updated
                        sortOrder:
                        - id: asc
                          label: Ascending
                        - id: desc
                          label: Descending
                    breadcrumbs: null
                    counts: null
                    permissions: null
        '400':
          description: |
            Invalid request parameters. The backend's validation message is
            returned verbatim in `error.message`. See the examples below for
            the common triggers.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                query_too_short:
                  summary: Search query shorter than 2 characters
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: Search query must be at least 2 characters
                comma_list_too_long:
                  summary: Comma-separated parameter exceeds 100 items
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Too many items in comma-separated list (max: 100, got: 142)'
                date_range_inverted:
                  summary: Date range with gte > lte
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Date range invalid: gte must be <= lte'
                size_exceeds_max:
                  summary: Size filter exceeds the 1 TB cap
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Size exceeds maximum (1TB): 2199023255552'
        '401':
          description: |
            Missing or invalid authentication token.

            The bearer token was absent, expired, malformed, or could not be
            verified by the auth middleware.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: HTTP_UNAUTHORIZED
                  message: Invalid token
        '403':
          description: |
            Insufficient OAuth scope.

            Only applies to OAuth tokens. The token did not carry the `kb:read`
            scope required by this endpoint. Regular (non-OAuth) JWT bearer
            tokens are not subject to scope enforcement and will not receive
            this error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: HTTP_FORBIDDEN
                  message: 'Insufficient scope. Required: kb:read'
        '422':
          description: |
            Either of:
            - A typed query parameter could not be read: `page` or `limit` is not an
              integer or is out of range (`page` below 1, `limit` outside 1-200),
              `onlyContainers` or `flattened` is not a boolean, or `page`/`limit` was
              sent more than once. `error.message` is the connector service's own
              validation text.
            - A listing that spans a whole connector (a flattened listing, a search or a filter) was too large for the
              database to hold in memory, so it was refused instead of cut short. No page is returned. Open a folder
              (`GET /knowledgeBase/knowledge-hub/nodes/{parentType}/{parentId}`) to see its records, or add a search (`q`),
              which keeps only matching records in memory. Choosing a connector, or a filter that keeps most records (such as
              `nodeTypes`), does not help. Sorting by name with no filters is served from stored visibility where the
              connector allows it and is not affected.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_UNPROCESSABLE_ENTITY
                        example: HTTP_UNPROCESSABLE_ENTITY
                      message:
                        type: string
                        example: This view has too many records to list at once. Open a folder, or narrow by search.
                      requestId:
                        type: string
        '503':
          description: |
            The database could not give this listing the memory it needs right now, because other requests were using
            it (nothing is wrong with the request). Retry after `Retry-After` seconds; the web app retries by itself.
            The body is the gateway's own busy message, not the service's wording.
          headers:
            Retry-After:
              description: Seconds to wait before retrying (5).
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_SERVICE_UNAVAILABLE
                        example: HTTP_SERVICE_UNAVAILABLE
                      message:
                        type: string
                        example: This part of PipesHub is briefly unavailable. Please try again in 5 seconds.
                      requestId:
                        type: string
        '500':
          description: |
            An unexpected error occurred on the server.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: HTTP_INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
  /knowledgeBase/knowledge-hub/nodes/{parentType}/{parentId}:
    get:
      deprecated: true
      x-speakeasy-deprecation-message: Use the Knowledge Base API instead. This grouping will be removed in a future release
      tags:
      - Knowledge Base
      - Knowledge Hub
      summary: Get knowledge hub child nodes
      description: |
        Returns the children of a specific node in the knowledge hub tree.
        Use this endpoint to drill down into Collections, connector app
        hierarchies, folders, and record groups.

        **Navigation hierarchy**

        The typical drill-down path is:
        1. Root apps (`GET /knowledgeBase/knowledge-hub/nodes`)
        2. Record groups / folders within an app (`parentType=app`)
        3. Records within a record group (`parentType=recordGroup`)
        4. Sub-records or attachments within a record (`parentType=record`)

        **Parent identification**

        - `parentType` must be one of: `app`, `recordGroup`, `folder`, `record`
        - `parentId` must be a standard UUID

        **Filtering and searching**

        All query-param filters from the root endpoint are available here and
        operate within the scope of the parent node's subtree. When `q` is
        provided, the search spans all descendants of the parent node.

        **Response extras**

        When `include=breadcrumbs` is set, the response contains a
        `breadcrumbs` array tracing the path from the root to the current
        node. The `currentNode` object is always populated for non-root
        requests. `parentNode` is too, except at the top of a source and for
        a connected app whose limit leaves that parent out: it is `null` then.

        **Access control**

        Requires a valid bearer token. For OAuth tokens the `kb:read` scope
        must be present; regular JWT bearer tokens pass through without scope
        enforcement.

        A parent the caller may not see, one in the trash, and one that does not
        exist are all answered `404` with the same body, so the route does not reveal
        whether the node exists.

        **Request checking**

        This route has no request validator of its own; the path values and the query
        are checked by the connector service. Query parameters not listed here are
        ignored. A wrong type for `page`, `limit`, `onlyContainers` or `flattened`
        (or `page` below 1 or `limit` outside 1-200) is answered `422`; other refusals,
        `page` above 50 and an unusable `cursor` included, are `400`.
      operationId: getKnowledgeHubChildNodes
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      parameters:
      - name: parentType
        in: path
        required: true
        description: |
          Type of the parent node whose children to retrieve.

          Must be one of: `app`, `recordGroup`, `folder`, `record` (case-sensitive).
          Any other value returns a 400 error, and so does a type that does not
          match what `parentId` is (for example `folder` with a knowledge base id).
        schema:
          type: string
          enum:
          - app
          - recordGroup
          - folder
          - record
      - name: parentId
        in: path
        required: true
        description: |
          Identifier of the parent node. Must be a valid UUID
          (e.g. `f3a4b5b6-5b6c-4e85-9097-3202cfe696fc`).

          Any value that does not match this format returns a 400 error. The format
          check ignores letter case but ids are stored in lower case, so an
          upper-case UUID passes the check and is answered 404.
        schema:
          type: string
          pattern: ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$
      - name: onlyContainers
        in: query
        required: false
        description: |
          When `true`, only nodes that have children are returned (useful for
          building sidebar / tree navigation). Leaf nodes are excluded.
        schema:
          type: boolean
          default: false
      - name: page
        in: query
        required: false
        description: |
          Page number (1-indexed, at most 50). Combined with `limit` to paginate results.
          Prefer `cursor`: a page number is reached by reading the pages before it.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: cursor
        in: query
        required: false
        description: |
          Opaque cursor from `pagination.nextCursor` or `pagination.prevCursor` of a previous
          response. It decides the listing mode, parent, filters and sort. `include` and
          `limit` come from this request. A next cursor returns the following page, and a previous
          cursor returns the page before. A cursor whose parent disagrees with the URL, or
          that was issued for another user, is refused with 400.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: |
          Maximum number of items to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
      - name: sortBy
        in: query
        required: false
        description: |
          Field to sort results by. Omitted → default `updatedAt`.
          Any other value is answered `400` ("Invalid sort_by: ...").
        schema:
          type: string
          enum:
          - name
          - createdAt
          - updatedAt
          - size
          - type
          default: updatedAt
      - name: sortOrder
        in: query
        required: false
        description: |
          Sort direction. Omitted → default `desc`. Read case-insensitively;
          any other value is answered `400` ("Invalid sort_order: ...").
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: q
        in: query
        required: false
        description: |
          Full-text search query. Must be between 2 and 500 characters
          (inclusive) after surrounding whitespace is removed, otherwise `400`.
          When provided, the endpoint searches across all
          descendants of the parent node.
          A repeated `q` is joined with commas into one query, and a `q` sent as an object
          (`q[a]=b`) is refused with `400` ("Search query must be text").
        schema:
          type: string
          minLength: 2
          maxLength: 500
        example: quarterly report
      - name: nodeTypes
        in: query
        required: false
        description: |
          Comma-separated list of node types to include. An unknown value is
          answered `400` ("Invalid node_types value(s): ..."). Maximum 100 items.

          Valid values: `folder`, `app`, `recordGroup`, `record`
        schema:
          type: string
        example: recordGroup
      - name: recordTypes
        in: query
        required: false
        description: |
          Comma-separated list of record types to include. An unknown value is
          answered `400` ("Invalid record_types value(s): ..."). Maximum 100 items.

          Valid values: `FILE`, `DRIVE`, `WEBPAGE`, `DATABASE`, `DATASOURCE`,
          `MESSAGE`, `MAIL`, `GROUP_MAIL`, `TICKET`, `COMMENT`,
          `INLINE_COMMENT`, `CONFLUENCE_PAGE`, `CONFLUENCE_BLOGPOST`,
          `SHAREPOINT_PAGE`, `SHAREPOINT_LIST`, `SHAREPOINT_LIST_ITEM`,
          `SHAREPOINT_DOCUMENT_LIBRARY`, `LINK`, `PROJECT`, `PULL_REQUEST`,
          `MEETING`, `PRODUCT`, `DEAL`, `CASE`, `TASK`, `ARTIFACT`,
          `CODE_FILE`, `SQL_TABLE`, `SQL_VIEW`, `OTHERS`
        schema:
          type: string
        example: FILE,CONFLUENCE_PAGE
      - name: origins
        in: query
        required: false
        description: |
          Comma-separated list of origin types to include. An unknown value is
          answered `400` ("Invalid origins value(s): ..."). Maximum 100 items.

          Valid values: `COLLECTION`, `CONNECTOR`
        schema:
          type: string
        example: CONNECTOR
      - name: connectorIds
        in: query
        required: false
        description: |
          Comma-separated list of connector instance IDs (UUIDs) to filter by.
          Maximum 100 items. No enum validation — any string is accepted, but
          non-existent IDs simply yield zero results.
        schema:
          type: string
        example: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
      - name: indexingStatus
        in: query
        required: false
        description: |
          Comma-separated list of indexing statuses to include. An unknown value
          is answered `400` ("Invalid indexing_status value(s): ..."). Maximum 100 items.

          Valid values: `NOT_STARTED`, `PAUSED`, `IN_PROGRESS`, `COMPLETED`,
          `FAILED`, `FILE_TYPE_NOT_SUPPORTED`, `AUTO_INDEX_OFF`, `EMPTY`,
          `ENABLE_MULTIMODAL_MODELS`, `QUEUED`, `SKIPPED`, `PASSWORD_PROTECTED`
        schema:
          type: string
        example: COMPLETED,FAILED
      - name: createdAt
        in: query
        required: false
        description: |
          Created-date range filter. Format: `gte:<epochMs>,lte:<epochMs>`.
          Both bounds are optional (you may send just `gte:...` or just
          `lte:...`). Timestamps must be in the range 0 to 9999999999999 and
          `gte` must be less than or equal to `lte` when both are present.
        schema:
          type: string
        example: gte:1700000000000,lte:1710000000000
      - name: updatedAt
        in: query
        required: false
        description: |
          Updated-date range filter. Same format and constraints as `createdAt`.
        schema:
          type: string
        example: gte:1700000000000,lte:1710000000000
      - name: size
        in: query
        required: false
        description: |
          File-size range filter in bytes. Format: `gte:<bytes>,lte:<bytes>`.
          Both bounds are optional. Values must be non-negative and at most
          1099511627776 (1 TB). `gte` must be less than or equal to `lte`
          when both are present.
        schema:
          type: string
        example: gte:0,lte:10485760
      - name: flattened
        in: query
        required: false
        description: |
          Force flattened/recursive search (`true`) or direct top-level
          listing (`false`). When omitted, it's computed from whether any
          of `q`, `nodeTypes`, `recordTypes`, `origins`, `connectorIds`,
          `indexingStatus`, `createdAt`, `updatedAt`, or `size` are present —
          if any are, results are flattened automatically; otherwise only
          top-level nodes are returned.
        schema:
          type: boolean
      - name: include
        in: query
        required: false
        description: |
          Comma-separated list of additional response sections to include.
          An unknown value is answered `400` ("Invalid include value(s): ...").
          Maximum 100 items.

          Valid values: `breadcrumbs`, `counts`, `availableFilters`, `permissions`
        schema:
          type: string
        example: breadcrumbs,availableFilters
      responses:
        '200':
          description: |
            Paginated children of `{parentType}/{parentId}`. HTTP 200 returns
            `success: true` and `error: null`; see `KnowledgeHubNodesResponse` for
            the full shape.

            `id` and `currentNode` reflect the parent being browsed; `parentNode`
            is set when a grandparent exists. Optional sections (`availableFilters`,
            `counts`, `permissions`, `breadcrumbs`) are JSON `null` unless listed
            in `include` and populated by the server.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeHubNodesResponse'
              examples:
                collection_record_groups:
                  summary: Record groups inside the Collection app with breadcrumbs
                  value:
                    success: true
                    error: null
                    id: c3d4e5f6-a7b8-9012-cdef-012345678901
                    currentNode:
                      id: c3d4e5f6-a7b8-9012-cdef-012345678901
                      name: My Knowledge Base
                      nodeType: app
                      subType: null
                    parentNode: null
                    items:
                    - id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      name: Engineering Docs
                      nodeType: record
                      parentId: c3d4e5f6-a7b8-9012-cdef-012345678901
                      origin: UPLOAD
                      connector: null
                      recordType: FILE
                      recordGroupType: null
                      indexingStatus: null
                      reason: null
                      createdAt: 1700000000000
                      updatedAt: 1709500000000
                      sizeInBytes: null
                      mimeType: application/vnd.folder
                      extension: null
                      webUrl: null
                      hasChildren: true
                      previewRenderable: null
                      permission: null
                      sharingStatus: workspace
                      isInternal: false
                      isPlaceholder: false
                    - id: b2c3d4e5-f6a7-8901-bcde-f12345678901
                      name: HR Policies
                      nodeType: record
                      parentId: c3d4e5f6-a7b8-9012-cdef-012345678901
                      origin: UPLOAD
                      connector: null
                      recordType: FILE
                      recordGroupType: null
                      indexingStatus: null
                      reason: null
                      createdAt: 1700100000000
                      updatedAt: 1709400000000
                      sizeInBytes: null
                      mimeType: application/vnd.folder
                      extension: null
                      webUrl: null
                      hasChildren: true
                      previewRenderable: null
                      permission: null
                      sharingStatus: private
                      isInternal: false
                      isPlaceholder: false
                    pagination:
                      page: 1
                      limit: 20
                      totalItems: 2
                      totalPages: 1
                      hasNext: false
                      hasPrev: false
                    filters:
                      applied:
                        q: null
                        nodeTypes:
                        - record
                        recordTypes: null
                        origins: null
                        connectorIds: null
                        indexingStatus: null
                        createdAt: null
                        updatedAt: null
                        size: null
                        sortBy: name
                        sortOrder: asc
                      available: null
                    breadcrumbs:
                    - id: c3d4e5f6-a7b8-9012-cdef-012345678901
                      name: My Knowledge Base
                      nodeType: app
                      subType: null
                    counts: null
                    permissions: null
        '400':
          description: |
            Invalid request parameters or path values. The backend's validation
            message is returned verbatim in `error.message`. See the examples
            below for the common triggers.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_parent_type:
                  summary: parentType outside the allowed set
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Invalid parent_type. Must be one of: app, recordGroup, folder, record'
                invalid_parent_id:
                  summary: parentId is not a valid UUID
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Invalid UUID format for parent_id: abc'
                parent_of_another_kind:
                  summary: parentId exists but is not a node of the given parentType
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Node type mismatch: node ''c3d4e5f6-a7b8-9012-cdef-012345678901'' is not ''folder'', it is ''app''. Use /nodes/app/c3d4e5f6-a7b8-9012-cdef-012345678901 instead.'
                unsafe_path_value:
                  summary: parentType or parentId holds a character that cannot stand in a URL path segment (such as `%`)
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: This address contains an ID that isn't valid. Check the link you followed and try again.
                query_too_short:
                  summary: Search query shorter than 2 characters
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: Search query must be at least 2 characters
                comma_list_too_long:
                  summary: Comma-separated parameter exceeds 100 items
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Too many items in comma-separated list (max: 100, got: 142)'
                date_range_inverted:
                  summary: Date range with gte > lte
                  value:
                    error:
                      code: HTTP_BAD_REQUEST
                      message: 'Date range invalid: gte must be <= lte'
        '401':
          description: |
            Missing or invalid authentication token.

            The bearer token was absent, expired, malformed, or could not be
            verified by the auth middleware.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: HTTP_UNAUTHORIZED
                  message: Invalid token
        '403':
          description: |
            Insufficient OAuth scope.

            Only applies to OAuth tokens. The token did not carry the `kb:read`
            scope required by this endpoint. Regular (non-OAuth) JWT bearer
            tokens are not subject to scope enforcement and will not receive
            this error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: HTTP_FORBIDDEN
                  message: 'Insufficient scope. Required: kb:read'
        '404':
          description: |
            Parent node not found (`Node not found`).

            The `parentId` does not correspond to an existing node, the node has
            been deleted, or the caller may not see it. A node that exists but is
            not of the given `parentType` is a `400` instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: HTTP_NOT_FOUND
                  message: Node not found
        '422':
          description: |
            Either of:
            - A typed query parameter could not be read: `page` or `limit` is not an
              integer or is out of range (`page` below 1, `limit` outside 1-200), or
              `onlyContainers` or `flattened` is not a boolean. `error.message` is the
              connector service's own validation text.
            - A listing that spans a whole connector (a flattened listing, a search or a filter) was too large for the
              database to hold in memory, so it was refused instead of cut short. No page is returned. Open a folder
              (`GET /knowledgeBase/knowledge-hub/nodes/{parentType}/{parentId}`) to see its records, or add a search (`q`),
              which keeps only matching records in memory. Choosing a connector, or a filter that keeps most records (such as
              `nodeTypes`), does not help. Sorting by name with no filters is served from stored visibility where the
              connector allows it and is not affected.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_UNPROCESSABLE_ENTITY
                        example: HTTP_UNPROCESSABLE_ENTITY
                      message:
                        type: string
                        example: This view has too many records to list at once. Open a folder, or narrow by search.
                      requestId:
                        type: string
        '503':
          description: |
            The database could not give this listing the memory it needs right now, because other requests were using
            it (nothing is wrong with the request). Retry after `Retry-After` seconds; the web app retries by itself.
            The body is the gateway's own busy message, not the service's wording.
          headers:
            Retry-After:
              description: Seconds to wait before retrying (5).
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: object
                    required:
                    - code
                    - message
                    properties:
                      code:
                        type: string
                        enum:
                        - HTTP_SERVICE_UNAVAILABLE
                        example: HTTP_SERVICE_UNAVAILABLE
                      message:
                        type: string
                        example: This part of PipesHub is briefly unavailable. Please try again in 5 seconds.
                      requestId:
                        type: string
        '500':
          description: |
            An unexpected error occurred on the server.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: HTTP_INTERNAL_SERVER_ERROR
                  message: An unexpected error occurred
  /conversations/create:
    post:
      tags:
      - Conversations
      summary: Create conversation (non-streaming)
      description: |
        Start a new assistant conversation and wait for the complete answer.
        The JSON counterpart of `POST /conversations/stream`, for API, SDK
        and automation callers that do not consume SSE.

        **How a turn runs**

        1. The user's message is saved (in its own short transaction on a
           replica set).
        2. The AI backend runs the same agent-loop pipeline as the `/stream`
           route and returns only its final result. No transaction is held
           during this call, and the call is never retried.
        3. The answer, citations and status are saved exactly as the
           streaming route saves them, and the updated conversation is
           returned.

        Every failure after step 1 is persisted: the conversation ends with
        status `Failed`, a `failReason`, and an `error` message, and the
        response carries `X-Conversation-Id` so the caller can fetch it.
        A 4xx from the AI backend (for example no model configured) keeps
        its status and user-facing message; other failures return 500 with
        a generic message.

        The response arrives only when the whole answer is ready, which can
        take minutes for agent runs. Allow a generous client and proxy
        timeout, or use the `/stream` variant for interactive clients.

        **Modes**

        `chatMode: agent` runs the universal agent and honours `tools` /
        `agentCapabilities`; `internal_search` and `web_search` run the
        search assistant and ignore `tools`. The legacy values `deep`,
        `quick`, `verification` and `auto` are accepted and run as internal
        search. Omitted, it defaults to internal search.
      operationId: createConversation
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:chat
      requestBody:
        required: true
        description: |
          The first question, with optional scope, model and mode. A `query` of only whitespace
          is refused with `400` `HTTP_BAD_REQUEST` ("Query is required"), after the validator
          and before any model runs.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversationRequest'
      responses:
        '201':
          description: Conversation created with its first answer.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConversationResponse'
        '400':
          description: |
            Invalid request — `query` is missing, empty or over 100,000
            characters, contains markup or printf-style format specifiers, or
            another field fails validation.

            A `previousConversations` field holding anything but an empty list (`HTTP_BAD_REQUEST`,
            `previousConversations is not accepted. Conversation history is read from the stored
            conversation: create the conversation, then send follow-up questions to its messages
            endpoint.`). Checked after authentication and before the body validator; an empty list is
            dropped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — valid bearer token required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — the token lacks the `conversation:chat` OAuth scope, or, with a `projectId`, lacks `project:read`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The `projectId` names a project that does not exist or that the caller cannot see (`HTTP_NOT_FOUND`), refused before a conversation is saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The `projectId` names an archived project (`HTTP_CONFLICT`); unarchive it to start chats in it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: The request is larger than the selected model accepts.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '422':
          description: The model provider's content filter blocked the request.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '424':
          description: |
            No usable LLM — none is configured for the organization, the
            selected one could not start, or its provider rejected the API
            key or could not find the model. The message says what to fix.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: The model provider is rate limiting or out of quota.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '500':
          description: |
            The answer failed (the AI service returned no answer, or it could
            not be saved). The conversation is kept with
            status `Failed` and an `error` message.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: |
            The AI service could not be reached (for example, it is still
            starting). The conversation is marked `Failed`; that save is best
            effort, so if it fails the conversation keeps its previous status.
            Sending the message again may repeat work the AI service had started.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: |
            The AI service did not answer in time. The conversation is marked
            `Failed`; that save is best effort, so if it fails the conversation
            keeps its previous status. The AI service may have started the turn,
            so sending the message again may repeat work it had started.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/stream:
    post:
      tags:
      - Conversations
      summary: Create conversation with streaming response
      description: |
        Start a new conversation and stream the AI response over Server-Sent
        Events (SSE). Behaves like `POST /conversations` but emits tokens,
        tool activity, and status updates incrementally instead of returning
        a single JSON response at the end.

        **Lifecycle**

        1. The server validates `query`, persists an in-progress
           conversation, then opens the SSE stream with HTTP `200`.
        2. A `CUSTOM` event named `conversation_created` is emitted
           immediately with the new `conversationId` so the client can link
           the stream (sidebar, parallel tabs, deep links) without an extra
           request.
        3. AI-backend events stream through (token chunks, tool calls,
           status, etc.).
        4. On success a single root `RUN_FINISHED` event is emitted carrying
           the full persisted conversation in `result`.
        5. On failure a root `RUN_ERROR` event is emitted and the
           conversation is marked FAILED before the stream closes.

        **Event vocabulary**

        AG-UI is the sole wire protocol. See `ConversationStreamSSEEvent`
        for the full event enum and payload guidance.

        Clients should ignore unknown event names rather than treating them
        as errors.

        **Agent mode**

        When `chatMode` is `agent`,
        the optional `tools` list restricts which tools the agent may
        invoke for this turn. Outside agent modes the `tools` field is
        ignored.
      operationId: streamChat
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:chat
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationStreamRequest'
      responses:
        '200':
          description: |
            SSE stream established. The body is a sequence of
            `text/event-stream` frames using the event vocabulary described
            above.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ConversationStreamSSEEvent'
        '400':
          description: |
            Invalid request — `query` is missing, empty, or exceeds the
            100000-character limit, or another field fails validation
            (for example a malformed `recordIds` or `currentTime`).

            A `previousConversations` field holding anything but an empty list (`HTTP_BAD_REQUEST`,
            `previousConversations is not accepted. Conversation history is read from the stored
            conversation: create the conversation, then send follow-up questions to its messages
            endpoint.`). Checked after authentication and before the body validator; an empty list is
            dropped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — valid bearer token required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden — the caller's token does not include the
            `conversation:chat` OAuth scope, or, with a `projectId`, does not
            include `project:read`. Returned before the SSE stream opens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The `projectId` names a project that does not exist or that the caller cannot see (`HTTP_NOT_FOUND`). Returned before the SSE stream opens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The `projectId` names an archived project (`HTTP_CONFLICT`); unarchive it to start chats in it. Returned before the SSE stream opens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error before the SSE stream is established (for
            example, the initial conversation row could not be persisted).
            Once the stream is open, terminal failures are surfaced as a
            `RUN_ERROR` SSE event instead of an HTTP status change.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations:
    get:
      tags:
      - Conversations
      summary: List all conversations
      description: |
        Retrieve paginated conversations for the authenticated user.

        **Overview:**

        Use the optional `source` query parameter to choose which list to return:
        `owned` — only conversations you own (`userId` matches the current user).
        `shared` — conversations where you have recipient access
        (`isShared` and your user appears in `sharedWith`), without the owner-only branch.
        Defaults to `owned` when omitted. Each call returns one list; call twice if you need both.

        **Filtering:**

        - Only non-archived conversations are returned by default
        - Use `/conversations/show/archives` for archived conversations

        **Sorting:**

        Conversations are sorted by last activity timestamp (most recent first) by default.
        With `source=owned`, conversations the caller pinned
        (`PATCH /conversations/{conversationId}/pin`) come first, in the same order,
        whatever `sortBy` is. `source=shared` is never pinned-first.

        Query parameters not listed here are ignored, not refused.
      operationId: getAllConversations
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:read
      parameters:
      - name: source
        in: query
        required: false
        description: |
          `owned` — owner list (`userId` filter only).
          `shared` — explicit share grant list (`isShared` + `sharedWith`). Includes agent
          conversations shared with the caller; those rows carry `agentKey`.
          Defaults to `owned` when omitted.
        schema:
          type: string
          enum:
          - owned
          - shared
          default: owned
      - name: page
        in: query
        required: false
        description: |
          Page number (1-based). Defaults to 1. The validator accepts any number, so a
          fraction such as `1.5` is not refused; it is truncated (`1.5` reads as page 1).
        schema:
          type: number
          minimum: 1
      - name: limit
        in: query
        required: false
        description: |
          Page size. Defaults to 10; values above 100, and fractions, are refused (`400 VALIDATION_ERROR`).
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
      - name: sortBy
        in: query
        required: false
        description: Sort field. Invalid values fall back to `lastActivityAt`.
        schema:
          type: string
          enum:
          - createdAt
          - lastActivityAt
          - title
      - name: sortOrder
        in: query
        required: false
        description: Sort direction. Defaults to `desc` unless set to `asc`.
        schema:
          type: string
          enum:
          - asc
          - desc
      - name: conversationId
        in: query
        required: false
        description: When set, restricts results to that conversation ID (if visible under the chosen `source`).
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{24}$
      - name: search
        in: query
        required: false
        description: Case-insensitive match on title and message content (max 1000 characters).
        schema:
          type: string
          maxLength: 1000
      - name: startDate
        in: query
        required: false
        description: |
          Filter by `createdAt` ≥ this instant. Must be a full ISO 8601
          date-time with `Z` or a numeric offset; a bare date is refused.
        schema:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$
      - name: endDate
        in: query
        required: false
        description: |
          Filter by `createdAt` ≤ this instant. Must be a full ISO 8601
          date-time with `Z` or a numeric offset; a bare date is refused.
        schema:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$
      - name: shared
        in: query
        required: false
        description: |
          When set, filters by `isShared`. Accepts exactly `true`,
          `false`, `1` or `0`.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      - name: projectId
        in: query
        required: false
        description: |
          Restrict results to a single project. Pass a project's `id` to
          list conversations linked to that project (visible to the
          caller — owner, member, or org-visible project with
          `projectVisibility: project`), or the literal string
          `unassigned` to list conversations with no `projectId`.
        schema:
          type: string
          pattern: ^(unassigned|[0-9a-fA-F]{24})$
      responses:
        '200':
          description: List of conversations for the requested source
          content:
            application/json:
              schema:
                type: object
                required:
                - conversations
                - source
                - pagination
                - filters
                - meta
                properties:
                  conversations:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConversationListItem'
                  source:
                    type: string
                    enum:
                    - owned
                    - shared
                    description: Echoes the requested `source` query value.
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      totalCount:
                        type: integer
                      totalPages:
                        type: integer
                      hasNextPage:
                        type: boolean
                      hasPrevPage:
                        type: boolean
                  filters:
                    type: object
                    additionalProperties: false
                    description: |
                      Filter introspection block. `applied` summarises the
                      filters active on this request; `available` catalogues
                      every supported filter with its current value and whether
                      it is applied.
                    required:
                    - applied
                    - available
                    properties:
                      applied:
                        type: object
                        additionalProperties: false
                        required:
                        - filters
                        - values
                        properties:
                          filters:
                            type: array
                            description: Names of filters currently applied.
                            items:
                              type: string
                          values:
                            type: object
                            additionalProperties: false
                            description: |
                              Current value for each applied filter. Only keys
                              present in `filters` are populated; others are
                              omitted.
                            properties:
                              search:
                                type: string
                              shared:
                                type: string
                              tags:
                                type: string
                              minMessages:
                                type: string
                              sortBy:
                                type: string
                              sortOrder:
                                type: string
                              startDate:
                                type: string
                              endDate:
                                type: string
                              messageType:
                                type: string
                              page:
                                type: integer
                              limit:
                                type: integer
                              dateRange:
                                type: object
                                additionalProperties: false
                                properties:
                                  start:
                                    type: string
                                    nullable: true
                                  end:
                                    type: string
                                    nullable: true
                      available:
                        type: object
                        additionalProperties: false
                        required:
                        - shared
                        - tags
                        - minMessages
                        - search
                        - pagination
                        - sorting
                        - dateFilters
                        - messageFilters
                        - sortingMessages
                        properties:
                          shared:
                            type: object
                            additionalProperties: false
                            properties:
                              values:
                                type: array
                                items:
                                  type: string
                                description: Accepted values for the `shared` query param.
                              description:
                                type: string
                              current:
                                type: string
                                nullable: true
                              applied:
                                type: boolean
                          tags:
                            type: object
                            additionalProperties: false
                            properties:
                              type:
                                type: string
                              description:
                                type: string
                              current:
                                type: string
                                nullable: true
                              applied:
                                type: boolean
                          minMessages:
                            type: object
                            additionalProperties: false
                            properties:
                              type:
                                type: string
                              description:
                                type: string
                              current:
                                type: number
                                nullable: true
                              applied:
                                type: boolean
                          search:
                            type: object
                            additionalProperties: false
                            properties:
                              type:
                                type: string
                              description:
                                type: string
                              current:
                                type: string
                                nullable: true
                              applied:
                                type: boolean
                          pagination:
                            type: object
                            additionalProperties: false
                            properties:
                              page:
                                type: object
                                additionalProperties: false
                                properties:
                                  type:
                                    type: string
                                  current:
                                    type: integer
                                  min:
                                    type: integer
                                  max:
                                    type: integer
                                  default:
                                    type: integer
                                  description:
                                    type: string
                                  applied:
                                    type: boolean
                              limit:
                                type: object
                                additionalProperties: false
                                properties:
                                  type:
                                    type: string
                                  current:
                                    type: integer
                                  min:
                                    type: integer
                                  max:
                                    type: integer
                                  default:
                                    type: integer
                                  description:
                                    type: string
                                  applied:
                                    type: boolean
                          sorting:
                            type: object
                            additionalProperties: false
                            properties:
                              sortBy:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  default:
                                    type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                                  applied:
                                    type: boolean
                              sortOrder:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  default:
                                    type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                                  applied:
                                    type: boolean
                          dateFilters:
                            type: object
                            additionalProperties: false
                            properties:
                              dateRange:
                                type: object
                                additionalProperties: false
                                properties:
                                  type:
                                    type: string
                                  description:
                                    type: string
                                  format:
                                    type: string
                                  current:
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      start:
                                        type: string
                                        nullable: true
                                      end:
                                        type: string
                                        nullable: true
                                  applied:
                                    type: boolean
                          messageFilters:
                            type: object
                            additionalProperties: false
                            properties:
                              messageType:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                                    nullable: true
                                  applied:
                                    type: boolean
                          sortingMessages:
                            type: object
                            additionalProperties: false
                            properties:
                              sortBy:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  default:
                                    type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                              sortOrder:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  default:
                                    type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                  meta:
                    type: object
                    properties:
                      requestId:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
                      duration:
                        type: integer
        '400':
          description: |
            Bad request — for example, missing or invalid `source` (must be `owned` or `shared`),
            invalid date query params, invalid `search` shape, or search text over the length limit.

            `limit` that is not a whole number is refused too (`VALIDATION_ERROR`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Valid bearer token required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — the OAuth token lacks the `conversation:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/show/archives:
    get:
      tags:
      - Conversations
      summary: List archived conversations
      description: |
        Retrieve all archived conversations for the authenticated user.

        **Overview:**

        Archived conversations are hidden from the main list but preserved for reference.
        This endpoint returns only conversations where `isArchived: true` and `archivedBy`
        is set. Results include conversations the caller owns and those shared with them
        (`isShared` and the caller listed in `sharedWith`). Deleted and agent
        conversations are never listed. Each item carries its `messages`.

        **Filtering and sorting:**

        Results can be narrowed using `search`, `shared`, `startDate`, `endDate`, and
        `conversationId`. Sorting is controlled by `sortBy` and `sortOrder`. Pagination
        is controlled by `page` and `limit`.

        Query parameters not listed here are dropped by the validator and
        ignored, including `projectId`, which `GET /conversations` accepts.

        **Unarchiving:**

        Use `PATCH /conversations/{conversationId}/unarchive` to restore a conversation
        to the active list.
      operationId: getArchivedConversations
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:read
      parameters:
      - name: page
        in: query
        required: false
        description: |
          Page number (1-indexed). The validator accepts any number, so a fraction such
          as `1.5` is not refused; it is truncated (`1.5` reads as page 1).
        schema:
          type: number
          minimum: 1
          maximum: 1000
          default: 1
      - name: limit
        in: query
        required: false
        description: |
          Items per page. A fraction is not refused; it is truncated (`5.5` reads as 5).
        schema:
          type: number
          minimum: 1
          maximum: 100
          default: 20
      - name: sortBy
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          enum:
          - createdAt
          - lastActivityAt
          - title
          default: lastActivityAt
      - name: sortOrder
        in: query
        required: false
        description: Sort direction
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: search
        in: query
        required: false
        description: |
          Case-insensitive substring match against title and message content
          (max 1000 chars). A value holding markup is refused by the
          controller with `400 HTTP_BAD_REQUEST`.
        schema:
          type: string
          maxLength: 1000
      - name: shared
        in: query
        required: false
        description: |
          When set, filters by `isShared`. Accepts exactly `true`, `false`,
          `1` or `0`.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      - name: startDate
        in: query
        required: false
        description: |
          Include conversations created on or after this instant. Must be a
          full ISO 8601 date-time with `Z` or a numeric offset; a bare date
          is refused.
        schema:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$
      - name: endDate
        in: query
        required: false
        description: |
          Include conversations created on or before this instant. Must be a
          full ISO 8601 date-time with `Z` or a numeric offset; a bare date
          is refused.
        schema:
          type: string
          format: date-time
          pattern: ^\d{4}-\d{2}-\d{2}T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(\.\d+)?(Z|[+-]\d{2}:?\d{2})$
      - name: conversationId
        in: query
        required: false
        description: Restrict results to a single conversation by identifier
        schema:
          type: string
          format: objectId
          pattern: ^[0-9a-fA-F]{24}$
      responses:
        '200':
          description: List of archived conversations
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  conversations:
                    type: array
                    description: Archived conversations matching the filter
                    items:
                      allOf:
                      - $ref: '#/components/schemas/Conversation'
                      - type: object
                        properties:
                          archivedAt:
                            type: string
                            format: date-time
                            description: Timestamp when the conversation was archived
                  pagination:
                    type: object
                    additionalProperties: false
                    properties:
                      page:
                        type: integer
                        description: Current page number
                      limit:
                        type: integer
                        description: Items per page
                      totalCount:
                        type: integer
                        description: Total archived conversations matching the filter
                      totalPages:
                        type: integer
                        description: Total pages at the current limit
                      hasNextPage:
                        type: boolean
                        description: Whether a next page exists
                      hasPrevPage:
                        type: boolean
                        description: Whether a previous page exists
                  filters:
                    type: object
                    additionalProperties: false
                    description: Filters applied to this request and filters available for clients to use
                    properties:
                      applied:
                        type: object
                        additionalProperties: false
                        properties:
                          filters:
                            type: array
                            description: Names of filters that were applied
                            items:
                              type: string
                          values:
                            type: object
                            additionalProperties: true
                            description: Map of applied filter name to its current value
                      available:
                        type: object
                        additionalProperties: false
                        description: Describes filters supported by this endpoint and their current values
                        properties:
                          shared:
                            type: object
                            additionalProperties: false
                            properties:
                              values:
                                type: array
                                items:
                                  type: string
                                description: Allowed values for the `shared` filter
                              description:
                                type: string
                              current:
                                type: string
                                nullable: true
                                description: Current value supplied by the caller, or null
                              applied:
                                type: boolean
                                description: Whether this filter was applied on the request
                          tags:
                            type: object
                            additionalProperties: false
                            properties:
                              type:
                                type: string
                                description: Expected value type
                              description:
                                type: string
                              current:
                                type: string
                                nullable: true
                              applied:
                                type: boolean
                          minMessages:
                            type: object
                            additionalProperties: false
                            properties:
                              type:
                                type: string
                              description:
                                type: string
                              current:
                                type: integer
                                nullable: true
                              applied:
                                type: boolean
                          search:
                            type: object
                            additionalProperties: false
                            properties:
                              type:
                                type: string
                              description:
                                type: string
                              current:
                                type: string
                                nullable: true
                              applied:
                                type: boolean
                          pagination:
                            type: object
                            additionalProperties: false
                            properties:
                              page:
                                type: object
                                additionalProperties: false
                                properties:
                                  type:
                                    type: string
                                  current:
                                    type: integer
                                  min:
                                    type: integer
                                  max:
                                    type: integer
                                  default:
                                    type: integer
                                  description:
                                    type: string
                                  applied:
                                    type: boolean
                              limit:
                                type: object
                                additionalProperties: false
                                properties:
                                  type:
                                    type: string
                                  current:
                                    type: integer
                                  min:
                                    type: integer
                                  max:
                                    type: integer
                                  default:
                                    type: integer
                                  description:
                                    type: string
                                  applied:
                                    type: boolean
                          sorting:
                            type: object
                            additionalProperties: false
                            properties:
                              sortBy:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  default:
                                    type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                                  applied:
                                    type: boolean
                              sortOrder:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                      enum:
                                      - asc
                                      - desc
                                  default:
                                    type: string
                                    enum:
                                    - asc
                                    - desc
                                  description:
                                    type: string
                                  current:
                                    type: string
                                    enum:
                                    - asc
                                    - desc
                                  applied:
                                    type: boolean
                          dateFilters:
                            type: object
                            additionalProperties: false
                            properties:
                              dateRange:
                                type: object
                                additionalProperties: false
                                properties:
                                  type:
                                    type: string
                                  description:
                                    type: string
                                  format:
                                    type: string
                                    description: Expected date format for `startDate` and `endDate` inputs
                                  current:
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      start:
                                        type: string
                                        format: date-time
                                        nullable: true
                                      end:
                                        type: string
                                        format: date-time
                                        nullable: true
                                  applied:
                                    type: boolean
                          messageFilters:
                            type: object
                            additionalProperties: false
                            properties:
                              messageType:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                                    nullable: true
                                  applied:
                                    type: boolean
                          sortingMessages:
                            type: object
                            additionalProperties: false
                            properties:
                              sortBy:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  default:
                                    type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                              sortOrder:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                      enum:
                                      - asc
                                      - desc
                                  default:
                                    type: string
                                    enum:
                                    - asc
                                    - desc
                                  description:
                                    type: string
                                  current:
                                    type: string
                                    enum:
                                    - asc
                                    - desc
                  summary:
                    type: object
                    additionalProperties: false
                    properties:
                      totalArchived:
                        type: integer
                        description: Total archived conversations matching the filter
                      oldestArchive:
                        type: string
                        format: date-time
                        description: Archive timestamp of the first item in the current page
                      newestArchive:
                        type: string
                        format: date-time
                        description: Archive timestamp of the last item in the current page
                  meta:
                    type: object
                    additionalProperties: false
                    properties:
                      requestId:
                        type: string
                        description: Request correlation identifier
                      timestamp:
                        type: string
                        format: date-time
                        description: Response generation timestamp
                      duration:
                        type: integer
                        description: Server processing time in milliseconds
        '400':
          description: |
            A query parameter failed validation (`VALIDATION_ERROR`), or
            `search` holds markup (`HTTP_BAD_REQUEST`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Token is missing the `conversation:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/show/archives/search:
    get:
      tags:
      - Conversations
      summary: Search archived conversations
      description: |
        Search across all archived conversations (assistant and agent) for the authenticated user.

        **Overview:**

        Performs a case-insensitive substring match against conversation titles and message content
        across both assistant (`Conversation`) and agent (`AgentConversation`) archived collections.
        Results are merged server-side and sorted by `lastActivityAt` descending.

        **Search parameter:**

        The `search` query parameter is required, must contain a non-space character, and is
        capped at 1000 characters; it is trimmed before use. Requests that omit it, send only
        spaces or exceed the cap return `400 VALIDATION_ERROR`. A value holding markup or a
        printf-style format specifier (such as `%s`) is refused by the controller with
        `400 HTTP_BAD_REQUEST`.

        Query parameters not listed here are dropped by the validator and ignored.

        **Pagination:**

        Results are paginated using `page` and `limit`. The response includes a `pagination`
        block with total counts and a `summary` block that breaks matches down by source.

        **Item shape:**

        Each item is a conversation list entry (no `messages` payload — that field is omitted
        for performance) tagged with `source`, plus computed `isOwner`, `accessLevel`,
        `archivedAt`, and `archivedBy`. `agentKey` is present only when `source` is `agent`.
      operationId: searchArchivedConversations
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:read
      parameters:
      - name: search
        in: query
        required: true
        description: Search term to match against conversation titles and message content (max 1000 chars)
        schema:
          type: string
          minLength: 1
          maxLength: 1000
          pattern: \S
      - name: page
        in: query
        required: false
        description: |
          Page number (1-indexed). The validator accepts any number, so a fraction such
          as `1.5` is not refused; it is truncated (`1.5` reads as page 1).
        schema:
          type: number
          minimum: 1
          maximum: 1000
          default: 1
      - name: limit
        in: query
        required: false
        description: |
          Items per page. A fraction is not refused; it is truncated (`5.5` reads as 5).
        schema:
          type: number
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: Search results across archived conversations
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  conversations:
                    type: array
                    description: Archived conversations (assistant and agent) matching the search term
                    items:
                      allOf:
                      - $ref: '#/components/schemas/ConversationListItem'
                      - type: object
                        properties:
                          source:
                            type: string
                            enum:
                            - assistant
                            - agent
                            description: Origin collection of the conversation
                          agentKey:
                            type: string
                            description: Agent identifier — present only when `source` is `agent`
                          archivedAt:
                            type: string
                            format: date-time
                            description: Timestamp when the conversation was archived
                  pagination:
                    type: object
                    additionalProperties: false
                    properties:
                      page:
                        type: integer
                        description: Current page number
                      limit:
                        type: integer
                        description: Items per page
                      totalCount:
                        type: integer
                        description: Total matches across assistant and agent archives
                      totalPages:
                        type: integer
                        description: Total pages at the current limit
                      hasNextPage:
                        type: boolean
                        description: Whether a next page exists
                      hasPrevPage:
                        type: boolean
                        description: Whether a previous page exists
                  summary:
                    type: object
                    additionalProperties: false
                    properties:
                      totalMatches:
                        type: integer
                        description: Combined match count across both collections
                      assistantMatches:
                        type: integer
                        description: Match count in the assistant (`Conversation`) collection
                      agentMatches:
                        type: integer
                        description: Match count in the agent (`AgentConversation`) collection
                      searchQuery:
                        type: string
                        description: Trimmed search term that was applied
                  meta:
                    type: object
                    additionalProperties: false
                    properties:
                      requestId:
                        type: string
                        description: Request correlation identifier
                      timestamp:
                        type: string
                        format: date-time
                        description: Response generation timestamp
                      duration:
                        type: integer
                        description: Server processing time in milliseconds
        '400':
          description: |
            `search` missing, blank, or longer than 1000 characters, or `page`
            or `limit` out of range (`VALIDATION_ERROR`); or `search` holds
            markup or a format specifier (`HTTP_BAD_REQUEST`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Token is missing the `conversation:read` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}:
    get:
      tags:
      - Conversations
      summary: Get conversation by ID
      description: |
        Retrieve a specific conversation with its full message history.

        **Overview:**

        Returns the complete conversation including all messages, citations,
        feedback, and metadata. Messages can be paginated for long conversations.

        **Message Pagination:**

        For conversations with many messages, use pagination parameters:

        - `page`: Page number (default: 1)
        - `limit`: Messages per page (default: 20)
        - `sortBy`: Sort field (default: createdAt)
        - `sortOrder`: 'asc' or 'desc' (default: desc)

        **Access Control:**

        Users can access conversations they own or that have been shared with them.

        Query parameters not listed here are ignored, not refused.
      operationId: getConversationById
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:read
      parameters:
      - name: conversationId
        in: path
        required: true
        description: Unique conversation identifier
        schema:
          type: string
          format: objectId
        example: 507f1f77bcf86cd799439011
      - name: page
        in: query
        description: |
          Page number for message pagination. Read with `parseInt`, so a fraction such
          as `1.5` is tolerated and truncated (page 1).
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: |
          Number of messages per page. Read with `parseInt`, so a fraction such as `5.5`
          is tolerated and truncated (5).
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: sortBy
        in: query
        description: Field to sort messages by
        schema:
          type: string
          enum:
          - createdAt
          - messageType
          - content
          default: createdAt
      - name: sortOrder
        in: query
        description: Sort direction
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: search
        in: query
        description: |
          Case-insensitive match against the conversation's title and its
          messages' content. Applies to the conversation, not its messages:
          when nothing matches the answer is `404`; when something matches
          every message is returned.
        schema:
          type: string
          maxLength: 1000
      - name: startDate
        in: query
        description: |
          Applies to the conversation, not its messages: when the
          conversation was created before this instant the answer is `404`.
          Any value JavaScript's `Date` parses is accepted (an ISO 8601
          date or date-time is the documented form); a value it cannot
          parse is refused with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      - name: endDate
        in: query
        description: |
          Applies to the conversation, not its messages: when the
          conversation was created after this instant the answer is `404`.
          Parsed like `startDate`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      - name: shared
        in: query
        description: |
          Filters on the conversation's `isShared`; a conversation that
          does not match is answered `404`. Read case-insensitively;
          any other value is refused with `400`.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      - name: projectId
        in: query
        description: |
          `unassigned` matches only a conversation linked to no project; a
          24-character ObjectId matches only a conversation linked to that
          project. A conversation that does not match is answered `404`.
          Any other value is ignored.
        schema:
          type: string
      - name: messageType
        in: query
        description: |
          Checked against the listed values (`400` otherwise) but not
          applied: every message type is returned.
        schema:
          type: string
          enum:
          - user_query
          - bot_response
          - error
          - feedback
          - system
          - tool_call
      responses:
        '200':
          description: Conversation with paginated messages, applied filter metadata, and request metadata
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  conversation:
                    type: object
                    additionalProperties: false
                    properties:
                      id:
                        type: string
                        format: objectId
                        description: Unique conversation identifier
                      title:
                        type: string
                        description: Conversation title
                      initiator:
                        type: string
                        format: objectId
                        description: User who started the conversation
                      createdAt:
                        type: string
                        format: date-time
                      isShared:
                        type: boolean
                      sharedWith:
                        type: array
                        items:
                          type: object
                          additionalProperties: false
                          properties:
                            userId:
                              type: string
                              format: objectId
                            accessLevel:
                              type: string
                              enum:
                              - read
                              - write
                            _id:
                              type: string
                              format: objectId
                              description: |
                                Id of the share entry. The session schema asks for none,
                                but Mongoose ignores that option and stores one.
                      status:
                        type: string
                        enum:
                        - None
                        - Inprogress
                        - Complete
                        - Failed
                        - Stopped
                      failReason:
                        type: string
                        description: Populated only when `status` is `Failed`
                      projectId:
                        type: string
                        format: objectId
                        description: Project the conversation is linked to. Absent when it is in none.
                      projectVisibility:
                        type: string
                        enum:
                        - private
                        - project
                        description: Who in the project sees the conversation. Absent when never set.
                      messages:
                        type: array
                        description: Page of messages, sliced by `pagination` and ordered by `sortingMessages`
                        items:
                          type: object
                          additionalProperties: false
                          properties:
                            _id:
                              type: string
                              format: objectId
                            messageType:
                              type: string
                              enum:
                              - user_query
                              - bot_response
                              - error
                              - feedback
                              - system
                              - tool_call
                            content:
                              type: string
                            contentFormat:
                              type: string
                              enum:
                              - MARKDOWN
                              - JSON
                              - HTML
                            confidence:
                              type: string
                              enum:
                              - Very High
                              - High
                              - Medium
                              - Low
                              - Unknown
                              nullable: true
                              description: |
                                AI confidence in the answer. Present only on `bot_response` messages, and only when the model emitted a trailing confidence block.

                                This field is now optional and nullable; it was previously always present and non-nullable. Treat a missing or `null` value as "no confidence reported" and guard before using it. Change effective in SDK v1.2.0 (v1.1.0 and earlier always populated it).
                            citations:
                              type: array
                              description: Citations attached to this message. `citationData` is the populated citation document.
                              items:
                                type: object
                                additionalProperties: false
                                properties:
                                  citationId:
                                    type: string
                                    format: objectId
                                  citationData:
                                    $ref: '#/components/schemas/Citation'
                            followUpQuestions:
                              type: array
                              items:
                                $ref: '#/components/schemas/FollowUpQuestion'
                            feedback:
                              type: array
                              items:
                                $ref: '#/components/schemas/MessageFeedback'
                            referenceData:
                              type: array
                              description: Reference IDs surfaced from tool responses, used for follow-up queries
                              items:
                                type: object
                                additionalProperties: false
                                properties:
                                  name:
                                    type: string
                                    description: Display name shown to the user.
                                  id:
                                    type: string
                                    description: Technical identifier (numeric ID, UUID, etc.).
                                  type:
                                    type: string
                                    description: Item type (e.g. `project`, `issue`, `file`, `notebook`, `page`).
                                  app:
                                    type: string
                                    description: |
                                      Source application (e.g. `jira`, `confluence`,
                                      `sharepoint`, `slack`, `drive`, `gmail`).
                                  webUrl:
                                    type: string
                                    description: URL to open the item in a browser.
                                  metadata:
                                    type: object
                                    additionalProperties:
                                      type: string
                                    description: |
                                      App-specific fields keyed by name (e.g. `key` for a Jira
                                      project, `siteId` for a SharePoint document).
                            modelInfo:
                              $ref: '#/components/schemas/ConversationModelInfo'
                            appliedFilters:
                              $ref: '#/components/schemas/AppliedFilters'
                            attachments:
                              type: array
                              description: |
                                Files uploaded for this message turn (see
                                `POST /conversations/attachments/upload`).
                              items:
                                $ref: '#/components/schemas/ChatAttachmentRef'
                            tools:
                              type: array
                              description: Tool call results invoked during this message turn.
                              items:
                                $ref: '#/components/schemas/MessageToolCall'
                            reasoning:
                              type: array
                              description: Persisted chain-of-thought for this turn.
                              items:
                                $ref: '#/components/schemas/MessageReasoningTurn'
                            parts:
                              type: array
                              description: Ordered agent-activity transcript for this turn.
                              items:
                                $ref: '#/components/schemas/MessagePart'
                            metadata:
                              type: object
                              additionalProperties: false
                              properties:
                                processingTimeMs:
                                  type: number
                                modelVersion:
                                  type: string
                                aiTransactionId:
                                  type: string
                            createdAt:
                              type: string
                              format: date-time
                            updatedAt:
                              type: string
                              format: date-time
                      modelInfo:
                        $ref: '#/components/schemas/ConversationModelInfo'
                      pagination:
                        type: object
                        additionalProperties: false
                        description: |
                          Pagination over the conversation's messages. Messages are paginated backwards
                          (newest first), so `messageRange.start`/`messageRange.end` refer to 1-based
                          positions within the full message list.
                        properties:
                          page:
                            type: integer
                          limit:
                            type: integer
                          totalCount:
                            type: integer
                            description: Total number of messages in the conversation
                          totalPages:
                            type: integer
                          hasNextPage:
                            type: boolean
                            description: True if there are older messages available
                          hasPrevPage:
                            type: boolean
                            description: True if there are newer messages available
                          messageRange:
                            type: object
                            additionalProperties: false
                            properties:
                              start:
                                type: integer
                              end:
                                type: integer
                      access:
                        type: object
                        additionalProperties: false
                        properties:
                          isOwner:
                            type: boolean
                          accessLevel:
                            type: string
                            enum:
                            - read
                            - write
                      sharedBy:
                        $ref: '#/components/schemas/ConversationSharedBy'
                  filters:
                    type: object
                    additionalProperties: false
                    description: Summary of which filter/sort/pagination parameters were applied to this request, plus the catalog of options available on this endpoint.
                    properties:
                      applied:
                        type: object
                        additionalProperties: false
                        properties:
                          filters:
                            type: array
                            description: Names of the filters/parameters that were actually applied
                            items:
                              type: string
                          values:
                            type: object
                            additionalProperties: true
                            description: Map of applied filter name to the value that was applied
                      available:
                        type: object
                        additionalProperties: false
                        properties:
                          shared:
                            type: object
                            additionalProperties: false
                            properties:
                              values:
                                type: array
                                items:
                                  type: string
                              description:
                                type: string
                              current:
                                type: string
                                nullable: true
                              applied:
                                type: boolean
                          tags:
                            type: object
                            additionalProperties: false
                            description: Advertised in the `available` catalog but not currently applied as a filter by the server.
                            properties:
                              type:
                                type: string
                              description:
                                type: string
                              current:
                                type: string
                                nullable: true
                              applied:
                                type: boolean
                          minMessages:
                            type: object
                            additionalProperties: false
                            description: Advertised in the `available` catalog but not currently applied as a filter by the server.
                            properties:
                              type:
                                type: string
                              description:
                                type: string
                              current:
                                type: string
                                nullable: true
                              applied:
                                type: boolean
                          search:
                            type: object
                            additionalProperties: false
                            properties:
                              type:
                                type: string
                              description:
                                type: string
                              current:
                                type: string
                                nullable: true
                              applied:
                                type: boolean
                          pagination:
                            type: object
                            additionalProperties: false
                            properties:
                              page:
                                type: object
                                additionalProperties: false
                                properties:
                                  type:
                                    type: string
                                  current:
                                    type: integer
                                  min:
                                    type: integer
                                  max:
                                    type: integer
                                  default:
                                    type: integer
                                  description:
                                    type: string
                                  applied:
                                    type: boolean
                              limit:
                                type: object
                                additionalProperties: false
                                properties:
                                  type:
                                    type: string
                                  current:
                                    type: integer
                                  min:
                                    type: integer
                                  max:
                                    type: integer
                                  default:
                                    type: integer
                                  description:
                                    type: string
                                  applied:
                                    type: boolean
                          sorting:
                            type: object
                            additionalProperties: false
                            description: Sort applied to the conversation list. Field set echoes back the original list-endpoint sort options even though this endpoint returns a single conversation.
                            properties:
                              sortBy:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  default:
                                    type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                                  applied:
                                    type: boolean
                              sortOrder:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  default:
                                    type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                                  applied:
                                    type: boolean
                          dateFilters:
                            type: object
                            additionalProperties: false
                            properties:
                              dateRange:
                                type: object
                                additionalProperties: false
                                properties:
                                  type:
                                    type: string
                                  description:
                                    type: string
                                  format:
                                    type: string
                                  current:
                                    type: object
                                    additionalProperties: false
                                    properties:
                                      start:
                                        type: string
                                        nullable: true
                                      end:
                                        type: string
                                        nullable: true
                                  applied:
                                    type: boolean
                          messageFilters:
                            type: object
                            additionalProperties: false
                            properties:
                              messageType:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                                    nullable: true
                                  applied:
                                    type: boolean
                          sortingMessages:
                            type: object
                            additionalProperties: false
                            description: Sort applied to messages within the conversation (separate from the conversation-list `sorting` block).
                            properties:
                              sortBy:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  default:
                                    type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                              sortOrder:
                                type: object
                                additionalProperties: false
                                properties:
                                  values:
                                    type: array
                                    items:
                                      type: string
                                  default:
                                    type: string
                                  description:
                                    type: string
                                  current:
                                    type: string
                  meta:
                    type: object
                    additionalProperties: false
                    properties:
                      requestId:
                        type: string
                      timestamp:
                        type: string
                        format: date-time
                      duration:
                        type: integer
                        description: Server processing time in milliseconds
                      conversationId:
                        type: string
                        format: objectId
                      messageCount:
                        type: integer
                        description: Total number of messages in the conversation
        '400':
          description: |
            `conversationId` is not an ObjectId (`VALIDATION_ERROR`), or a
            query parameter is refused by the controller (`HTTP_BAD_REQUEST`):
            `page` or `limit` not an integer in range, `sortBy` or
            `messageType` not a listed value, `startDate`/`endDate` not a
            date, `shared` not a boolean, or `search` over 1000 characters or
            containing markup.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden — the OAuth token lacks the `conversation:read` scope.
            A conversation the caller may not see is answered `404`, not `403`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Conversation not found: it does not exist, is deleted, is an agent
            conversation, the caller neither owns it nor has it shared with
            them (directly or through its project), or a query filter
            (`search`, `startDate`, `endDate`, `shared`, `projectId`)
            excludes it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Conversations
      summary: Delete conversation
      description: |
        Delete a conversation by its ID.

        **Overview:**

        Performs a soft delete by setting `isDeleted: true`. The conversation is
        removed from listings but preserved in the database. All citations
        referenced by messages in the conversation are also soft-deleted.

        **Permissions:**

        Only the conversation's owner can delete it. The lookup also allows a
        user the conversation is shared with at `write` access, but it
        requires the caller to be the owner as well, so such a user is
        answered `404`.

        **Artifacts:** before the conversation is marked deleted, every artifact
        the caller created in it is deleted for good (every version and stored
        file), and so are older stored outputs of the conversation. If that cannot
        be done the conversation is left in place and the error is returned
        (for example 503); repeating the request finishes the cleanup.
      operationId: deleteConversationById
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:write
      parameters:
      - name: conversationId
        in: path
        required: true
        description: Unique conversation identifier
        schema:
          type: string
          format: objectId
      responses:
        '200':
          description: Conversation deleted successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id:
                    type: string
                    format: objectId
                    description: Identifier of the conversation that was deleted
                  status:
                    type: string
                    enum:
                    - deleted
                    description: Outcome of the operation
                  deletedAt:
                    type: string
                    format: date-time
                    description: Timestamp when the conversation was marked deleted
                  deletedBy:
                    type: string
                    format: objectId
                    description: Identifier of the user who performed the delete
                  citationsDeleted:
                    type: integer
                    description: Number of citations soft-deleted alongside the conversation
                  meta:
                    type: object
                    additionalProperties: false
                    properties:
                      requestId:
                        type: string
                        description: Server-assigned identifier for the request
                      timestamp:
                        type: string
                        format: date-time
                        description: Server time the response was produced
                      duration:
                        type: integer
                        description: Server processing time in milliseconds
        '400':
          description: |
            Invalid `conversationId` path parameter

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - token is missing the `conversation:write` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conversation not found, already deleted, or caller has no delete access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while deleting the conversation.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/messages:
    post:
      tags:
      - Conversations
      summary: Add message (non-streaming)
      description: |
        Ask a follow-up in an existing assistant conversation and wait for
        the complete answer. The JSON counterpart of
        `POST /conversations/{conversationId}/messages/stream`. Earlier turns
        are sent to the model as history; project context comes from the
        conversation, never from the request.

        **How a turn runs**

        1. The user's message is saved (in its own short transaction on a
           replica set).
        2. The AI backend runs the same agent-loop pipeline as the `/stream`
           route and returns only its final result. No transaction is held
           during this call, and the call is never retried.
        3. The answer, citations and status are saved exactly as the
           streaming route saves them, and the updated conversation is
           returned.

        Every failure after step 1 is persisted: the conversation ends with
        status `Failed`, a `failReason`, and an `error` message, and the
        response carries `X-Conversation-Id` so the caller can fetch it.
        A 4xx from the AI backend (for example no model configured) keeps
        its status and user-facing message; other failures return 500 with
        a generic message.

        The response arrives only when the whole answer is ready, which can
        take minutes for agent runs. Allow a generous client and proxy
        timeout, or use the `/stream` variant for interactive clients.
      operationId: addMessage
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:chat
      parameters:
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        description: |
          The follow-up question, with optional scope and model overrides. A `query` of only
          whitespace is refused with `400` `HTTP_BAD_REQUEST` ("Query is required"), after the
          validator and before any model runs.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddMessageRequest'
      responses:
        '200':
          description: The conversation with the new question and answer.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddMessageResponse'
        '400':
          description: |
            Invalid request — `query` is missing, empty or over 100,000
            characters, contains markup or printf-style format specifiers, or
            another field fails validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — valid bearer token required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — the token lacks the `conversation:chat` OAuth scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Conversation not found — it does not exist, belongs to another
            user, is of the other type (assistant vs agent), or, for agent
            routes, belongs to a different agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: The request is larger than the selected model accepts.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '422':
          description: The model provider's content filter blocked the request.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '424':
          description: |
            No usable LLM — none is configured for the organization, the
            selected one could not start, or its provider rejected the API
            key or could not find the model. The message says what to fix.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: The model provider is rate limiting or out of quota.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '500':
          description: |
            The answer failed (the AI service returned no answer, or it could
            not be saved). The conversation is kept with
            status `Failed` and an `error` message.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: |
            The AI service could not be reached (for example, it is still
            starting). The conversation is marked `Failed`; that save is best
            effort, so if it fails the conversation keeps its previous status.
            Sending the message again may repeat work the AI service had started.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: |
            The AI service did not answer in time. The conversation is marked
            `Failed`; that save is best effort, so if it fails the conversation
            keeps its previous status. The AI service may have started the turn,
            so sending the message again may repeat work it had started.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/messages/stream:
    post:
      tags:
      - Conversations
      summary: Add message to a conversation with streaming response
      description: |
        Add a follow-up message to an existing conversation and stream the
        assistant's response over Server-Sent Events.

        Functionally equivalent to `POST /conversations/{conversationId}/messages`
        but the response is delivered as an SSE stream so clients can render
        the answer incrementally.

        AG-UI is the sole wire protocol. The vocabulary is described by
        `ConversationMessageStreamSSEEvent`; it is the same event set as
        `/conversations/stream`, while the terminal result reflects an
        existing conversation.
      operationId: addMessageStream
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:chat
      parameters:
      - name: conversationId
        in: path
        required: true
        description: |
          Identifier of the conversation to append the message to. The
          conversation must belong to the caller and must not be deleted.
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationMessageStreamRequest'
      responses:
        '200':
          description: |
            SSE stream established. The body is a sequence of
            `text/event-stream` frames using the event vocabulary described
            on the schema below.

            The conversation is looked up only after the stream is open, so
            a conversation that does not exist, is deleted, belongs to
            another user or is an agent conversation is not answered `404`:
            the stream is `200` and carries a `CUSTOM` `conversation_created`
            frame echoing the path's `conversationId`, then a single
            `RUN_ERROR` with `message: "Conversation not found"` and
            `code: "internal_error"`.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/ConversationMessageStreamSSEEvent'
        '400':
          description: |
            Invalid request — `query` is missing, empty or over 100,000
            characters, or another field fails validation (for example a
            malformed `currentTime`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — valid bearer token required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden — the caller's token does not include the
            `conversation:chat` OAuth scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error before the SSE stream is established (for
            example, the user message could not be persisted to the
            conversation). Once the stream is open, terminal failures are
            surfaced as a `RUN_ERROR` SSE event instead of an HTTP status
            change.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/title:
    patch:
      tags:
      - Conversations
      summary: Update conversation title
      description: |
        Update the title of a conversation.

        **Overview:**

        Conversation titles are auto-generated from the first query by default.
        Use this endpoint to set a custom, more descriptive title.

        **Title limits:**

        - Minimum: 1 character
        - Maximum: 200 characters

        **Permissions:**

        The conversation must exist, belong to the calling user's organization,
        be owned by the caller (matched on `userId`), not be soft-deleted, and
        not be an agent conversation. A user it is shared with, even at
        `write` access, gets `404`.

        Body fields other than `title` are dropped by the validator, not
        refused.
      operationId: updateConversationTitle
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:write
      parameters:
      - name: conversationId
        in: path
        required: true
        description: Unique conversation identifier
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - title
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 200
                  pattern: \S
                  description: |
                    New conversation title. Surrounding whitespace is trimmed before
                    validation, so a title of only whitespace is refused with `400`
                    `VALIDATION_ERROR` ("Title is required").
                  example: Q4 Sales Analysis Discussion
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              required:
              - title
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 200
                  pattern: \S
                  description: |
                    New conversation title. Surrounding whitespace is trimmed before
                    validation, so a title of only whitespace is refused with `400`
                    `VALIDATION_ERROR` ("Title is required").
                  example: Q4 Sales Analysis Discussion
      responses:
        '200':
          description: Title updated successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - conversation
                - meta
                properties:
                  conversation:
                    type: object
                    additionalProperties: false
                    description: |
                      The conversation document after the title update, as
                      stored in the `chatSessions` collection.

                      Carries no `messages`: they live in `chatSessionMessages`
                      (see `chat.session.schema.ts`) and this route neither
                      reads nor joins them. Fetch the conversation by id to
                      get its messages.
                    required:
                    - _id
                    - userId
                    - orgId
                    - initiator
                    - isShared
                    - isDeleted
                    - isArchived
                    - sharedWith
                    - conversationErrors
                    - lastActivityAt
                    - createdAt
                    - updatedAt
                    - __v
                    properties:
                      _id:
                        type: string
                        format: objectId
                        description: Unique conversation identifier
                      userId:
                        type: string
                        format: objectId
                        description: ID of the user who owns this conversation
                      orgId:
                        type: string
                        format: objectId
                        description: Organization this conversation belongs to
                      title:
                        type: string
                        description: |
                          Conversation title. Present and equal to the value
                          submitted in the request body after a successful
                          update.
                      initiator:
                        type: string
                        format: objectId
                        description: User who started the conversation
                      status:
                        type: string
                        enum:
                        - None
                        - Inprogress
                        - Complete
                        - Failed
                        - Stopped
                        description: |
                          Current status of the conversation:
                          - `None` — no activity yet
                          - `Inprogress` — AI is processing
                          - `Complete` — response ready
                          - `Failed` — error occurred
                          - `Stopped` — cancelled, or the client disconnected mid-answer
                      failReason:
                        type: string
                        description: |
                          Error description, populated only when `status`
                          is `Failed`.
                      modelInfo:
                        $ref: '#/components/schemas/ConversationModelInfo'
                      isShared:
                        type: boolean
                        default: false
                        description: Whether this conversation is shared with others
                      shareLink:
                        type: string
                        description: Shareable link if the conversation is shared
                      sharedWith:
                        type: array
                        description: Users this conversation is shared with
                        items:
                          type: object
                          additionalProperties: false
                          required:
                          - userId
                          - accessLevel
                          properties:
                            userId:
                              type: string
                              format: objectId
                            accessLevel:
                              type: string
                              enum:
                              - read
                              - write
                              default: read
                            _id:
                              type: string
                              format: objectId
                              description: Subdocument identifier auto-assigned by MongoDB.
                      isArchived:
                        type: boolean
                        default: false
                        description: Whether this conversation is archived
                      archivedBy:
                        type: string
                        format: objectId
                        nullable: true
                        description: |
                          User ID of the last user who archived this row, or `null` after
                          unarchive cleared the archive state. Absent on rows that have
                          never been archived.
                      isDeleted:
                        type: boolean
                        default: false
                        description: Whether this conversation has been soft-deleted.
                      deletedBy:
                        type: string
                        format: objectId
                        description: User who soft-deleted this conversation.
                      conversationErrors:
                        type: array
                        description: |
                          Errors recorded against this conversation
                          (e.g. failed message generations).
                        items:
                          type: object
                          additionalProperties: false
                          required:
                          - _id
                          - message
                          - timestamp
                          properties:
                            _id:
                              type: string
                              format: objectId
                              description: Sub-document identifier auto-assigned by MongoDB.
                            message:
                              type: string
                            errorType:
                              type: string
                            timestamp:
                              type: string
                              format: date-time
                              description: |
                                Time the error was recorded. Server-defaulted
                                to `Date.now` when the entry is pushed, so
                                always present.
                            messageId:
                              type: string
                              format: objectId
                            stack:
                              type: string
                            metadata:
                              type: object
                              additionalProperties: true
                              description: |
                                Free-form metadata attached to this error
                                entry (Map of Mixed in the schema).
                      metadata:
                        type: object
                        additionalProperties: true
                        description: Free-form metadata attached to the conversation.
                      lastActivityAt:
                        type: integer
                        format: int64
                        description: |
                          Unix timestamp of the last activity, stored as
                          epoch milliseconds (server-side default `Date.now`).
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
                      __v:
                        type: integer
                        description: Mongoose document version key.
                  meta:
                    type: object
                    additionalProperties: false
                    required:
                    - requestId
                    - timestamp
                    - duration
                    properties:
                      requestId:
                        type: string
                        description: |
                          Server-side request identifier. Read from the
                          `X-Request-ID` header when supplied, otherwise
                          auto-generated, so this field is always present.
                      timestamp:
                        type: string
                        format: date-time
                      duration:
                        type: integer
                        description: Server-side processing time in milliseconds.
        '400':
          description: |
            Invalid request. Possible causes:

            - `title` missing, empty, or longer than 200 characters.
            - `conversationId` path parameter is not a valid ObjectId.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - token is missing the `conversation:write` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conversation not found, soft-deleted, an agent conversation, or not owned by the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Persistence layer failed to update the conversation document.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/archive:
    patch:
      tags:
      - Conversations
      summary: Archive conversation
      description: |
        Archive a conversation to hide it from the main list.

        **Overview:**

        Archived conversations are preserved but hidden from the default conversation list.
        Use archiving to clean up your workspace without permanently deleting conversations.

        **Access:**

        Only the conversation's owner can archive it: the lookup filters on
        the caller's `userId`. It also has a branch for users the
        conversation is shared with at `write` access, but that branch can
        never match, so such users get `404` (a known defect). A missing,
        deleted or agent conversation is `404` too.
        Already-archived conversations return `400`.

        **Retrieval:**

        View archived conversations using `GET /conversations/show/archives`.
        Restore one with `PATCH /conversations/{conversationId}/unarchive`.
      operationId: archiveConversation
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:write
      parameters:
      - name: conversationId
        in: path
        required: true
        description: Conversation identifier
        schema:
          type: string
          format: objectId
      responses:
        '200':
          description: Conversation archived successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id:
                    type: string
                    format: objectId
                    description: Conversation identifier
                  status:
                    type: string
                    enum:
                    - archived
                    description: New archive status of the conversation
                  archivedBy:
                    type: string
                    format: objectId
                    description: User who archived the conversation
                  archivedAt:
                    type: string
                    format: date-time
                    description: Timestamp when the conversation was archived
                  meta:
                    type: object
                    additionalProperties: false
                    properties:
                      requestId:
                        type: string
                        description: Request correlation identifier
                      timestamp:
                        type: string
                        format: date-time
                        description: Response generation timestamp
                      duration:
                        type: integer
                        description: Server processing time in milliseconds
        '400':
          description: |
            Conversation is already archived

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Token is missing the `conversation:write` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conversation not found or caller lacks archive permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/unarchive:
    patch:
      tags:
      - Conversations
      summary: Unarchive conversation
      description: |
        Restore an archived conversation.

        - Path params: `conversationId`
        - Query params: none
        - Body: none

        **Access:**

        Only the conversation's owner can unarchive it: the lookup filters on
        the caller's `userId`. It also has a branch for users the
        conversation is shared with at `write` access, but that branch can
        never match, so such users get `404` (a known defect). A missing,
        deleted or agent conversation is `404` too.
        A conversation that is not archived returns `400`.
      operationId: unarchiveConversation
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:write
      parameters:
      - name: conversationId
        in: path
        required: true
        description: Conversation identifier
        schema:
          type: string
          format: objectId
      responses:
        '200':
          description: Conversation unarchived successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id:
                    type: string
                    format: objectId
                    description: Conversation identifier
                  status:
                    type: string
                    enum:
                    - unarchived
                    description: New archive status of the conversation
                  unarchivedBy:
                    type: string
                    format: objectId
                    description: User who unarchived the conversation
                  unarchivedAt:
                    type: string
                    format: date-time
                    description: Timestamp when the conversation was unarchived
                  meta:
                    type: object
                    additionalProperties: false
                    properties:
                      requestId:
                        type: string
                        description: Request correlation identifier
                      timestamp:
                        type: string
                        format: date-time
                        description: Response generation timestamp
                      duration:
                        type: integer
                        description: Server processing time in milliseconds
        '400':
          description: |
            Conversation is not currently archived

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - token is missing the `conversation:write` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conversation not found or caller lacks unarchive permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Persistence layer failed to update the conversation document.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/pin:
    patch:
      tags:
      - Conversations
      summary: Pin conversation
      description: |
        Pin a conversation so it is listed first in the caller's own conversation list.

        **Access:**

        Owner only: the caller must be the conversation's `initiator`. People the
        conversation is shared with, even with `write` access, cannot pin it, and
        their own lists are not affected by the owner's pin.

        **Behaviour:**

        Idempotent: pinning an already pinned conversation succeeds and changes nothing.
        Archived and deleted conversations cannot be pinned. Archiving a pinned
        conversation removes its pin. Pinning does not change `lastActivityAt` or
        `updatedAt`, so the conversation keeps its place among the other pinned chats.

        - Path params: `conversationId`
        - Query params: none
        - Body: none
      operationId: pinConversation
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:write
      parameters:
      - name: conversationId
        in: path
        required: true
        description: Conversation identifier
        schema:
          type: string
          format: objectId
      responses:
        '200':
          description: Conversation is pinned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationPinResponse'
        '400':
          description: |
            Missing user or organization context, or `conversationId` is not a valid id
            (`VALIDATION_ERROR`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - token is missing the `conversation:write` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conversation not found, deleted, archived, an agent conversation, or not owned by the caller (`Conversation not found or not owned by caller`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Persistence layer failed to update the conversation document.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/unpin:
    patch:
      tags:
      - Conversations
      summary: Unpin conversation
      description: |
        Remove a conversation's pin so it is listed by recent activity again.

        **Access:**

        Owner only, as for `PATCH /conversations/{conversationId}/pin`.

        **Behaviour:**

        Idempotent: unpinning a conversation that is not pinned succeeds and changes nothing.

        - Path params: `conversationId`
        - Query params: none
        - Body: none
      operationId: unpinConversation
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:write
      parameters:
      - name: conversationId
        in: path
        required: true
        description: Conversation identifier
        schema:
          type: string
          format: objectId
      responses:
        '200':
          description: Conversation is not pinned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationPinResponse'
        '400':
          description: |
            Missing user or organization context, or `conversationId` is not a valid id
            (`VALIDATION_ERROR`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - token is missing the `conversation:write` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conversation not found, deleted, an agent conversation, or not owned by the caller (`Conversation not found or not owned by caller`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Persistence layer failed to update the conversation document.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/message/{messageId}/regenerate:
    post:
      tags:
      - Conversations
      summary: Regenerate AI response
      description: |
        Regenerate the AI response for a specific message and stream the new
        answer over Server-Sent Events.

        **Overview:**

        If you're not satisfied with an AI response, use this endpoint to generate
        a new answer. The original user query is re-processed and a new bot
        response replaces the previous one in place.

        **Constraints:**

        - Only the *last* message of the conversation can be regenerated.
        - The target message must be of type `bot_response`.

        **Editing the question:**

        Send `query` to re-ask the last question with new wording. The answer
        is regenerated for the edited question, which replaces the stored one
        once the new answer is saved.

        **Use Cases:**

        - Response was incomplete or unclear
        - Want to try a different AI model
        - New documents have been indexed since original response

        **Model Override:**

        Specify `modelKey` to use a different model for regeneration.

        **Streaming:**

        The response is delivered as an AG-UI `text/event-stream` stream.
        Routing still depends on `chatMode`: `internal_search` and
        `web_search` use the assistant backend, while `agent` uses the
        universal agent loop. See `SSEEvent` for the event vocabulary.
      operationId: regenerateAnswer
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:chat
      parameters:
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      - name: messageId
        in: path
        required: true
        description: ID of the message to regenerate response for
        schema:
          type: string
          format: objectId
      requestBody:
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegenerateRequest'
      responses:
        '200':
          description: |
            SSE stream established. The body is a sequence of
            `text/event-stream` frames using the event vocabulary described
            on `SSEEvent`. The exact subset of events emitted depends on
            `chatMode` (see the route description for routing rules).

            The gateway emits a root `RUN_FINISHED` as `{ type, result }`
            after persistence and a root `RUN_ERROR` as
            `{ type, message, code? }` on failure. Forwarded lifecycle and
            child-run events may contain `runId`, `threadId`, and
            `parentRunId`. Clients should ignore unknown event names.

            Refusals after validation are not HTTP errors. A missing, deleted
            or inaccessible conversation, a conversation with no messages, a
            target that is not the latest `bot_response`, or no preceding
            `user_query` each produce a 200 stream holding the opening
            `CUSTOM` `conversation_created` frame and one root `RUN_ERROR`
            (`code: streaming_error`) whose `message` names the cause.

            Two refusals about `answers` arrive the same way: `Answers can only replace the answers to a
            question card.` and `An edit cannot also replace the answers to a question card.`
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/SSEEvent'
        '400':
          description: |
            The request validator refused the body or a path id
            (`VALIDATION_ERROR`). The conditions listed under **Constraints**
            are not answered with 400: they arrive as a `RUN_ERROR` frame in
            a 200 stream.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Token is missing the `conversation:chat` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/message/{messageId}/fork:
    post:
      tags:
      - Conversations
      summary: Fork conversation from a message
      description: |
        Copy this conversation into a new private chat owned by the caller,
        including every message up to and including `messageId`. The original
        conversation is left unchanged.

        Only the owner of the conversation can fork it. A shared recipient or a
        project member gets 404, because their access to the original's
        attachments and artifacts is revoked on unshare. The fork does not
        inherit share settings. If the source is linked to a project the caller
        can still see, the fork stays in that project but is private to the
        caller; otherwise it is created outside the project.
      operationId: forkConversation
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:chat
      parameters:
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      - name: messageId
        in: path
        required: true
        description: Inclusive last message to copy into the new chat
        schema:
          type: string
          format: objectId
      responses:
        '201':
          description: Forked conversation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForkConversationResponse'
        '400':
          description: Invalid conversation or message id (`VALIDATION_ERROR`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - token is missing the `conversation:chat` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            `Conversation not found` when the conversation does not exist, is deleted, archived
            or an agent conversation, or is not the caller's own; `Message not found` when
            `messageId` is not a message of that conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error, for example when an artifact of the conversation could not
            be copied into the fork (`Could not copy <n> artifact(s) into the fork`); no fork is
            created then.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/cancel:
    post:
      tags:
      - Conversations
      summary: Cancel an in-flight chat stream
      description: |
        Cooperatively stop a `POST /conversations/stream` or
        `POST /conversations/{conversationId}/messages/stream` run that is
        still generating, using the `runId` sent when that stream started.

        This is a synchronous JSON ack, not another SSE stream. The
        cancelled run's own stream (if still connected) receives a terminal
        frame with a `stopped` status and whatever partial answer had
        already generated; nothing further is delivered here.

        A `runId` that already finished or was never registered is not an
        error either, but it is answered `{ cancelled: true }`, not `false`:
        the query service's KV-backed run registry publishes the cancel for
        other workers and acknowledges it as cancelled (a known defect).
        `{ cancelled: false }` is only returned when that publish fails.

        Only the conversation's owner (matched on `userId`) can cancel; any
        other caller, or a missing, deleted or agent conversation, is `404`.

        `runId` must belong to a run started on THIS `conversationId` — a
        `runId` that exists but was registered under a different
        conversation (even one owned by the same caller) is rejected with
        `403`, same as a `runId` owned by a different user/org.
      operationId: cancelConversationStream
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:chat
      parameters:
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - runId
              properties:
                runId:
                  type: string
                  format: uuid
                  pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                  description: The `runId` sent when the stream was started.
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - runId
              properties:
                runId:
                  type: string
                  format: uuid
                  pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                  description: The `runId` sent when the stream was started.
      responses:
        '200':
          description: Cancellation requested, or the run had already finished.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - cancelled
                properties:
                  cancelled:
                    type: boolean
        '400':
          description: |
            `runId` missing or not a UUID, or `conversationId` not an
            ObjectId (`VALIDATION_ERROR`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            The token is missing the `conversation:chat` scope (`Insufficient
            scope`), or `runId` is a running stream registered under a
            different user, org or conversation than this request (`You do
            not own this run`, relayed from the query service).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conversation not found or unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /conversations/{conversationId}/message/{messageId}/feedback:
    post:
      tags:
      - Conversations
      summary: Submit feedback on AI response
      description: |
        Append a feedback entry to a bot-response message.

        **Overview**

        Feedback helps improve AI response quality over time. You can record an
        overall helpfulness signal, issue categories, and free-text comments.
        Each call appends a new entry to the message; previous entries are
        preserved.

        **Feedback options**

        - `isHelpful` — overall thumbs up/down.
        - `categories` — issue or positive categories from a fixed list.
        - `comments` — free-text `positive` and `negative`.

        **Restrictions**

        Feedback can only be submitted on `bot_response` messages — user
        queries and system messages are rejected with `400`.

        **Who can submit**

        The conversation's initiator, or any user it is shared with (at any
        access level) while `isShared` is `true`. Agent conversations are
        `404` here.

        Body fields other than `isHelpful`, `categories` and `comments` are
        dropped by the validator, not refused. `metrics` is always computed
        by the server.
      operationId: updateMessageFeedback
      security:
      - bearerAuth: []
      - oauth2:
        - conversation:write
      parameters:
      - name: conversationId
        in: path
        required: true
        description: Unique conversation identifier.
        schema:
          type: string
          format: objectId
      - name: messageId
        in: path
        required: true
        description: Identifier of the bot-response message being rated.
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageFeedbackSubmitRequest'
      responses:
        '200':
          description: Feedback submitted successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageFeedbackUpdateResponse'
        '400':
          description: |
            Invalid request. Possible causes:

            - Feedback target is not a `bot_response` message
              (`HTTP_BAD_REQUEST`).
            - `isHelpful` is not a boolean, `categories` is not a list of
              allowed values, or a `comments` value is not a string
              (`VALIDATION_ERROR`).
            - `conversationId` or `messageId` is not a valid ObjectId
              (`VALIDATION_ERROR`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Token is missing the `conversation:write` scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            The conversation does not exist, is deleted, is an agent
            conversation, or the caller neither started it nor has it shared
            with them (`Conversation not found`); or the message does not
            exist in that conversation (`Message not found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Persistence layer failed to append the feedback entry.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /retrieve:
    post:
      tags:
      - Semantic Search
      summary: Retrieve chunks with citations
      description: |
        Ranked passages ("chunks") for a query, each with its record and a
        citation link, for building your own RAG pipeline or agent on
        PipesHub. Results are filtered by the caller's permissions exactly as
        `POST /search` is, and take the same `filters` and date bounds.

        Unlike `POST /search`, nothing is stored: no search history and no
        citation documents, so an application can call this on every request
        it serves. The query text is always searched; `rewriteQuery` adds the
        model's rewritten and expanded versions.

        Nothing to find (no match, no accessible records, nothing indexed
        yet) is a `200` with an empty `chunks` list.
      operationId: retrieve
      security:
      - bearerAuth: []
      - oauth2:
        - semantic:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrieveRequest'
            examples:
              simple:
                summary: Chunks from one collection
                value:
                  query: how do we roll back a canary?
                  limit: 8
                  filters:
                    kb:
                    - 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90
      responses:
        '200':
          description: Ranked chunks, each with its record and citation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrieveResponse'
        '400':
          description: |
            Invalid request. `VALIDATION_ERROR` when `query` is missing, empty, not text or longer than
            100,000 characters, `limit` or `maxChunksPerRecord` is not a whole number from 1 to 50 (a
            numeric string such as `"8"` is refused too: unlike `POST /search`, these are not read as
            numbers), `filters` is not an object or holds a key the `Filters` schema does not list (the
            message names it and lists the allowed keys), an entry of `filters.apps`, `filters.kb`,
            `filters.recordGroups`, `filters.records` or `filters.recordsExact` is not a UUID, more than 200
            ids are sent across those keys, `filters.where` is sent at all, `rewriteQuery` is not a
            boolean, or a date bound is empty or longer than 64 characters (`A date filter cannot be
            empty`, `A date filter must be at most 64 characters`).
            `HTTP_BAD_REQUEST` when the query contains a format specifier (`retrieve query contains
            potentially dangerous format specifiers. ...`), or from the search service when a date bound
            is not a date it accepts. Markup in `query` is not refused: the app-wide markup filter skips
            this one field. Unknown body fields are dropped, not refused.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            Missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            The OAuth token lacks the `semantic:write` scope (`Insufficient scope. Required: semantic:write`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            A `recordGroups`, `records` or `recordsExact` selection resolves to
            nothing the caller can read (as for `POST /search`). An app or
            collection id that does not exist or is not readable is not a 404:
            it is a `200` with no chunks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: |
            The selection cannot be searched as asked (as for `POST /search`);
            the message says what to change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Unexpected server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: |
            The AI search service could not be reached (for example, it is
            still starting), or the search index or the permission check is
            temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: The AI search service did not answer in time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /search:
    post:
      tags:
      - Semantic Search
      summary: Perform semantic search
      description: |
        Run a semantic search across your organization's knowledge base.
        Matching is meaning-based, so relevant results surface even when
        the wording differs from the query.

        Use optional `filters` to narrow the scope (see `Filters`):

        - `filters.apps` — restrict to whole apps: connector instances
          (for example Google Drive or Confluence) and collections.
          `filters.kb` is the older name for collections and means the
          same.
        - `filters.recordGroups` — restrict to record groups (a drive, a
          space, a project), each with the groups nested in it.
        - `filters.records` — restrict to folders or records, each with
          everything under it.
        - `filters.recordsExact` — restrict to records alone, without
          what is under them.

        The keys are a union. With any of the last three present, an
        absent or empty `apps` / `kb` means no whole app.

        The response returns a `searchId` for the persisted search along
        with ranked matches, each carrying a relevance score and the
        source document's metadata. Past searches can be retrieved via
        `GET /search`. With `saveHistory: false` nothing is saved and
        there is no `searchId`.

        **Scopes:** an OAuth token needs `semantic:write`. The gateway also lets a token holding
        only `semantic:read` through, but the search service then refuses it with the same `403`
        ("Insufficient scope. Required: semantic:write"). Known defect.
      operationId: search
      security:
      - bearerAuth: []
      - oauth2:
        - semantic:write
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SemanticSearchRequest'
            examples:
              simple:
                summary: Basic search
                value:
                  query: company vacation policy
                  limit: 10
      responses:
        '200':
          description: Search ID plus retrieval payload (`searchResponse`) from the AI search service
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SemanticSearchExecuteResponse'
        '400':
          description: |
            Invalid request. `VALIDATION_ERROR` when `query` is missing, empty or not text,
            `limit` is below 1, above 100, not a whole number or not a number, `filters` is not
            an object, `filters` holds a key the `Filters` schema does not list (the message
            names it and lists the allowed keys), an
            entry of `filters.apps`, `filters.kb`, `filters.recordGroups`, `filters.records` or
            `filters.recordsExact` is not a UUID (`Must be a valid UUID`), more than 200 ids are
            sent across those keys (`At most 200 ids may be selected in one request`),
            `filters.entityFilters` is unusable, `filters.where` is sent at all
            (`filters.where is not supported yet`), `rewriteQuery` is not a boolean,
            `timeline` is not one of its values, or a date bound (`createdAfter`,
            `createdBefore`, `modifiedAfter`, `modifiedBefore`) is empty or longer than 64
            characters. The gateway validates before the search service, so clients see 400
            for these, never 422.
            `HTTP_BAD_REQUEST` when the query contains a format specifier, or from the search
            service when a date bound is not a date it accepts, an after bound is later than
            its before bound, or an after bound is in the future. Markup in `query` is
            not refused: the app-wide markup filter skips this one field (see "Behaviour common
            to every route" in the API description). Unknown body fields are dropped, not refused.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            Missing or invalid bearer token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Bearer token lacks the `semantic:write` scope. A token holding neither `semantic:read`
            nor `semantic:write` is refused by the gateway ("Insufficient scope. Required:
            semantic:read or semantic:write"), before the body is validated. One holding only
            `semantic:read` passes the gateway and the body check, and is then refused by the
            search service ("Insufficient scope. Required: semantic:write").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            The search service found nothing the caller is allowed to
            search — no indexed document is accessible to the caller, or
            none remains inside the scope set by `filters`, or nothing
            selected below app level exists or is readable by the caller
            ("Nothing in your selection is available to search"). The
            search is not persisted in this case.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: |
            The search service refused the request after the gateway accepted it:
            - `filters.entityFilters` matches too many records the caller can read. Narrow it:
              a tighter range, a name, or fewer kinds.
            - the selection below app level covers more nodes than one search may (50,000 by
              default) or touches a source that is still being prepared for folder-level search.
            The message says which and what to change.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Unexpected server error while executing the search.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: |
            The upstream AI search service returned an invalid response.
        '503':
          description: |
            The upstream AI search service is temporarily unavailable, or
            could not be reached (for example, it is still starting).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: |
            The upstream AI search service timed out before returning a
            response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Semantic Search
      summary: Get search history
      description: |
        Retrieve the authenticated user's persisted search history.

        Returns searches the user owns along with searches shared with them,
        scoped to the caller's organization. Archived and deleted entries are
        excluded. Citation references on this endpoint are returned as raw
        identifier strings; use `GET /search/{searchId}` to fetch a single
        search with its citations fully expanded.

        Pagination defaults to `page=1, limit=20` (maximum `limit` is 100).
        Results are sorted by most recent activity by default.

        `pagination.totalCount` (and with it `totalPages` and `hasNextPage`)
        counts the searches the listing itself holds: the caller's own and those
        shared with them in their organization.
      operationId: searchHistory
      security:
      - bearerAuth: []
      - oauth2:
        - semantic:read
      parameters:
      - name: page
        in: query
        description: |
          Page number to return, from 1. An empty value means `1`. The value is read with
          `parseInt`, so a fraction or trailing text is truncated (`2.5` reads as page `2`)
          instead of refused. `0`, a negative value, a value that is not a number, or one
          above 90071992547409 is refused with `400`.
        allowEmptyValue: true
        schema:
          type: integer
          minimum: 1
          maximum: 90071992547409
          default: 1
      - name: limit
        in: query
        description: |
          Number of items per page. An empty value means `20`. Read with `parseInt` like
          `page`; a value outside `[1, 100]` or not a number is refused with `400`, not
          clamped.
        allowEmptyValue: true
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: sortBy
        in: query
        description: |
          Field used to sort results. Any value other than `createdAt`,
          `lastActivityAt`, or `title` is treated as `lastActivityAt`.
        schema:
          type: string
          enum:
          - createdAt
          - lastActivityAt
          - title
          default: lastActivityAt
      - name: sortOrder
        in: query
        description: |
          Sort direction applied to `sortBy`. Only the exact, case-sensitive value `asc` sorts
          ascending; any other value (`ASC`, `sideways`, ...) is accepted and sorts descending.
          The raw value is echoed in `filters.applied.values.sortOrder`.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: search
        in: query
        description: |
          Meant as a case-insensitive substring filter on a search's title, but a stored
          search has no title, so the filter is dropped and every search is still returned.
          The value is still checked: more than 1000 characters, or HTML markup, is refused
          with `400`.
        schema:
          type: string
          maxLength: 1000
      - name: shared
        in: query
        description: |
          Filter results by their shared status. Accepted values are
          `'true'` / `'1'` (return only shared searches) and
          `'false'` / `'0'` (exclude shared searches). Matching is
          case-insensitive and surrounding whitespace is trimmed.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      - name: startDate
        in: query
        description: |
          ISO 8601 date or date-time used as the inclusive lower bound for a search's creation
          date. A value JavaScript's `Date` cannot parse is refused with `400` ("Invalid start
          date format").
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      - name: endDate
        in: query
        description: |
          ISO 8601 date or date-time used as the inclusive upper bound for a search's creation
          date. A value JavaScript's `Date` cannot parse is refused with `400` ("Invalid end
          date format").
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      responses:
        '200':
          description: |
            Persisted search history plus pagination, applied/available filter
            metadata, and a request-scoped `meta` block.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SemanticSearchHistoryResponse'
        '400':
          description: |
            Invalid request (`HTTP_BAD_REQUEST`; the route has no request validator): `page` or
            `limit` is not a number or out of range, `shared` is not a boolean, `startDate` or
            `endDate` cannot be parsed as a date, `search` is over 1000 characters, or a query
            value contains HTML markup.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: Error envelope for a failed request.
                properties:
                  error:
                    type: object
                    additionalProperties: false
                    description: Error payload.
                    properties:
                      requestId:
                        type: string
                        description: |
                          Identifier for this request, echoed so a bug report can quote it.
                          Absent when the request never reached the middleware that assigns one.
                      code:
                        type: string
                        description: |
                          Machine-readable error code. For this status the
                          value is either `VALIDATION_ERROR` (request failed
                          schema validation) or `HTTP_BAD_REQUEST` (semantic
                          validation failed — malformed date, value over the
                          allowed length, or XSS-guard trip).
                      message:
                        type: string
                        description: Human-readable description of the failure.
                    required:
                    - code
                    - message
                required:
                - error
        '401':
          description: |
            Missing or invalid bearer token.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: Error envelope for a failed request.
                properties:
                  error:
                    type: object
                    additionalProperties: false
                    description: Error payload.
                    properties:
                      requestId:
                        type: string
                        description: |
                          Identifier for this request, echoed so a bug report can quote it.
                          Absent when the request never reached the middleware that assigns one.
                      code:
                        type: string
                        description: |
                          Machine-readable error code. For this status the
                          value is `HTTP_UNAUTHORIZED` (missing, invalid, or
                          expired bearer token, user no longer exists, or the
                          session has been invalidated).
                      message:
                        type: string
                        description: Human-readable description of the failure.
                    required:
                    - code
                    - message
                required:
                - error
        '403':
          description: |
            Bearer token lacks the `semantic:read` scope.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: Error envelope for a failed request.
                properties:
                  error:
                    type: object
                    additionalProperties: false
                    description: Error payload.
                    properties:
                      requestId:
                        type: string
                        description: |
                          Identifier for this request, echoed so a bug report can quote it.
                          Absent when the request never reached the middleware that assigns one.
                      code:
                        type: string
                        description: |
                          Machine-readable error code. For this status the
                          value is `HTTP_FORBIDDEN` (the token is valid but
                          does not carry the `semantic:read` scope).
                      message:
                        type: string
                        description: Human-readable description of the failure.
                    required:
                    - code
                    - message
                required:
                - error
        '500':
          description: |
            Server error. Possible causes:

            - Explicit `InternalServerError`
              or any other 500 `BaseError` thrown by the handler.
            - Non-`BaseError` exception caught by the
              global error middleware.
            - Response serializer fallback.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: Error envelope for a failed request.
                properties:
                  error:
                    type: object
                    additionalProperties: false
                    description: Error payload.
                    properties:
                      requestId:
                        type: string
                        description: |
                          Identifier for this request, echoed so a bug report can quote it.
                          Absent when the request never reached the middleware that assigns one.
                      code:
                        type: string
                        description: |
                          Machine-readable error code. For this status the
                          value is `HTTP_INTERNAL_SERVER_ERROR` for an
                          explicit server-side failure, or `INTERNAL_ERROR`
                          for an unhandled exception coerced by the global
                          error middleware.
                      message:
                        type: string
                        description: Human-readable description of the failure.
                    required:
                    - code
                    - message
                required:
                - error
    delete:
      tags:
      - Semantic Search
      summary: Clear all search history
      description: |
        Permanently delete every persisted search row owned by, or shared
        with, the authenticated user, along with the citation rows those
        searches reference. The action cannot be undone. Searches other
        users shared with the caller are deleted for their owners too, even
        when the caller only has `read` access.

        Scoped to the caller's org and limited to rows where
        `isArchived: false`. The optional `shared`, `startDate` and
        `endDate` query filters narrow what is deleted; `search` is
        validated but has no effect. If nothing matches (including the case
        where every row is already archived), the endpoint returns `404`
        rather than a successful no-op.
      operationId: deleteSearchHistory
      security:
      - bearerAuth: []
      - oauth2:
        - semantic:delete
      parameters:
      - name: search
        in: query
        description: |
          Validated, then dropped: a stored search has no title to match, so it never narrows
          the deletion. More than 1000 characters, or HTML markup, is refused with `400`.
        schema:
          type: string
          maxLength: 1000
      - name: shared
        in: query
        description: |
          Restrict the deletion to rows with this `isShared` value. `'true'` / `'1'` and
          `'false'` / `'0'`, case-insensitive; anything else is refused with `400`.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      - name: startDate
        in: query
        description: |
          ISO 8601 date or date-time lower bound for `createdAt`. A value JavaScript's `Date`
          cannot parse is refused with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      - name: endDate
        in: query
        description: |
          ISO 8601 date or date-time upper bound for `createdAt`. A value JavaScript's `Date`
          cannot parse is refused with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      responses:
        '200':
          description: Search history deleted successfully.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - message
                properties:
                  message:
                    type: string
        '400':
          description: |
            Invalid query filter (`HTTP_BAD_REQUEST`; the route has no request validator):
            `shared` is not a boolean, `startDate` / `endDate` cannot be parsed, or `search` is
            over 1000 characters or contains HTML markup.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            Missing or invalid bearer token (`HTTP_UNAUTHORIZED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            OAuth access token without the `semantic:delete` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            No matching rows (`HTTP_NOT_FOUND`, "Search history not found"). Returned when the
            caller has no owned or shared, unarchived searches that satisfy the filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Unexpected server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /search/{searchId}:
    get:
      tags:
      - Semantic Search
      summary: Get search by ID
      description: |
        Retrieve a previously persisted search by its id, scoped to the
        caller's org. The caller must own the search or have it shared with
        them; archived searches are not returned.

        The response body is always an **array** containing zero or one
        persisted search document. An unknown id, a search the caller
        cannot see, an archived search, or one that fails a query filter
        all return an empty array with a `200` status — this route never
        answers `404`, so callers should check the array length.

        The optional `shared`, `startDate` and `endDate` query filters are
        applied to the one search; `search` is validated but has no effect.
      operationId: getSearchById
      security:
      - bearerAuth: []
      - oauth2:
        - semantic:read
      parameters:
      - name: searchId
        in: path
        required: true
        description: Unique search identifier
        schema:
          type: string
          format: objectId
      - name: search
        in: query
        description: |
          Validated, then dropped: a stored search has no title to match, so it never
          filters anything. More than 1000 characters, or HTML markup, is refused with `400`.
        schema:
          type: string
          maxLength: 1000
      - name: shared
        in: query
        description: |
          Return the search only if its `isShared` matches. `'true'` / `'1'` and `'false'` /
          `'0'`, case-insensitive; anything else is refused with `400`.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      - name: startDate
        in: query
        description: |
          ISO 8601 date or date-time; return the search only if it was created on or after
          it. A value JavaScript's `Date` cannot parse is refused with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      - name: endDate
        in: query
        description: |
          ISO 8601 date or date-time; return the search only if it was created on or before
          it. A value JavaScript's `Date` cannot parse is refused with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      responses:
        '200':
          description: Array containing zero or one persisted search document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersistedSemanticSearchEnvelope'
        '400':
          description: |
            Invalid request. `VALIDATION_ERROR` naming `params.searchId` when `searchId` is not
            a 24-character hex id. `HTTP_BAD_REQUEST` when a query filter is invalid: `shared`
            is not a boolean, `startDate` / `endDate` cannot be parsed, or `search` is over 1000
            characters or contains HTML markup.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            Missing or invalid bearer token (`HTTP_UNAUTHORIZED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            OAuth access token without the `semantic:read` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Unexpected server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Semantic Search
      summary: Delete search by ID
      description: |
        Permanently delete a single persisted search row, plus every
        citation row referenced by its `citationIds`. The caller must
        either own the row or have it shared with them: a user the search
        was shared with, even with `read` access only, deletes the owner's
        search for everyone.

        Scoped to the caller's org and limited to rows where
        `isArchived: false`; an archived or already-deleted row is `404`.
        The optional `shared`, `startDate` and `endDate` query filters must
        also match, otherwise `404`; `search` is validated but has no effect.
      operationId: deleteSearchById
      security:
      - bearerAuth: []
      - oauth2:
        - semantic:delete
      parameters:
      - name: searchId
        in: path
        required: true
        description: ObjectId of the persisted search row to delete.
        schema:
          type: string
          format: objectId
      - name: search
        in: query
        description: |
          Validated, then dropped: a stored search has no title to match, so the row is
          deleted whatever this says. More than 1000 characters, or HTML markup, is refused
          with `400`.
        schema:
          type: string
          maxLength: 1000
      - name: shared
        in: query
        description: |
          Additional `isShared` filter. `'true'` / `'1'` and `'false'` / `'0'`,
          case-insensitive; anything else is refused with `400`. The row is only deleted if
          it matches.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      - name: startDate
        in: query
        description: |
          ISO 8601 date or date-time lower bound for `createdAt`. The row is only deleted if
          it was created on or after it. A value JavaScript's `Date` cannot parse is refused
          with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      - name: endDate
        in: query
        description: |
          ISO 8601 date or date-time upper bound for `createdAt`. The row is only deleted if
          it was created on or before it. A value JavaScript's `Date` cannot parse is refused
          with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      responses:
        '200':
          description: Search deleted successfully.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - message
                properties:
                  message:
                    type: string
        '400':
          description: |
            Invalid request. `VALIDATION_ERROR` naming `params.searchId` when `searchId` is not
            a 24-character hex id. `HTTP_BAD_REQUEST` when a query filter is invalid: `shared`
            is not a boolean, `startDate` / `endDate` cannot be parsed, or `search` is over 1000
            characters or contains HTML markup.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            Missing or invalid bearer token (`HTTP_UNAUTHORIZED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            OAuth access token without the `semantic:delete` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            No search matched (`HTTP_NOT_FOUND`, "Search Id not found"). Returned when the id
            does not exist for this caller, the caller neither owns it nor has it shared with
            them, the row is archived or already deleted, or a query filter does not match it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Unexpected server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /search/{searchId}/archive:
    patch:
      tags:
      - Semantic Search
      summary: Archive a search
      description: |
        Archive a specific search result. Archived searches are hidden
        from the search history and from `GET /search/{searchId}`, and
        cannot be shared, unshared or deleted until they are unarchived.

        The caller must own the search or have it shared with them: a user
        the search was shared with, even with `read` access only, can
        archive the owner's search for everyone.
      operationId: archiveSearch
      security:
      - bearerAuth: []
      - oauth2:
        - semantic:write
      parameters:
      - name: searchId
        in: path
        required: true
        description: Unique search identifier
        schema:
          type: string
          format: objectId
      - name: search
        in: query
        description: |
          Validated, then dropped: a stored search has no title to match, so the search is
          archived whatever this says. More than 1000 characters, or HTML markup, is refused
          with `400`.
        schema:
          type: string
          maxLength: 1000
      - name: shared
        in: query
        description: |
          Additional `isShared` filter. `'true'` / `'1'` and `'false'` / `'0'`,
          case-insensitive; anything else is refused with `400`. The search is only archived
          if it matches, otherwise `404`.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      - name: startDate
        in: query
        description: |
          ISO 8601 date or date-time lower bound for `createdAt`. The search is only archived
          if it was created on or after it, otherwise `404`. A value JavaScript's `Date`
          cannot parse is refused with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      - name: endDate
        in: query
        description: |
          ISO 8601 date or date-time upper bound for `createdAt`. The search is only archived
          if it was created on or before it, otherwise `404`. A value JavaScript's `Date`
          cannot parse is refused with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      responses:
        '200':
          description: Search archived successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - id
                - status
                - archivedBy
                - archivedAt
                - meta
                properties:
                  id:
                    type: string
                    format: objectId
                    description: Unique identifier of the archived search.
                    example: 65f1c0a4e2b9c4d8f3a1b2c3
                  status:
                    type: string
                    enum:
                    - archived
                    description: Resulting status of the search after the operation.
                    example: archived
                  archivedBy:
                    type: string
                    format: objectId
                    description: User ID of the user who archived the search.
                    example: 65f1c0a4e2b9c4d8f3a1b2c4
                  archivedAt:
                    type: string
                    format: date-time
                    description: Timestamp when the search was archived.
                    example: '2026-05-10T12:34:56.789Z'
                  meta:
                    type: object
                    additionalProperties: false
                    required:
                    - timestamp
                    - duration
                    properties:
                      requestId:
                        type: string
                        description: Server-assigned request identifier for tracing. Omitted when not available.
                        example: req_8f3a1b2c
                      timestamp:
                        type: string
                        format: date-time
                        description: Server timestamp when the response was produced.
                        example: '2026-05-10T12:34:56.789Z'
                      duration:
                        type: integer
                        description: Time taken to process the request, in milliseconds.
                        example: 42
        '400':
          description: |
            Invalid request. `VALIDATION_ERROR` naming `params.searchId` when `searchId` is not
            a 24-character hex id. `HTTP_BAD_REQUEST` when a query filter is invalid: `shared`
            is not a boolean, `startDate` / `endDate` cannot be parsed, or `search` is over 1000
            characters or contains HTML markup. An already archived search
            is `404`, not `400`.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            Missing or invalid bearer token (`HTTP_UNAUTHORIZED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            OAuth access token without the `semantic:write` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            No active search matched (`HTTP_NOT_FOUND`, "Search Id not found or no archive
            permission"): the id does not exist in the caller's org, the caller neither owns
            the search nor has it shared with them, it is already archived, or a `shared`,
            `startDate` or `endDate` query filter does not match it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The search document could not be updated.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /search/{searchId}/unarchive:
    patch:
      tags:
      - Semantic Search
      summary: Unarchive a search
      description: |
        Restore a previously archived search result back to the active search history.
        The owner or any user the search was shared with can unarchive it.
      operationId: unarchiveSearch
      security:
      - bearerAuth: []
      - oauth2:
        - semantic:write
      parameters:
      - name: searchId
        in: path
        required: true
        description: Unique search identifier
        schema:
          type: string
          format: objectId
      - name: search
        in: query
        description: |
          Validated, then dropped: a stored search has no title to match, so the search is
          unarchived whatever this says. More than 1000 characters, or HTML markup, is refused
          with `400`.
        schema:
          type: string
          maxLength: 1000
      - name: shared
        in: query
        description: |
          Additional `isShared` filter. `'true'` / `'1'` and `'false'` / `'0'`,
          case-insensitive; anything else is refused with `400`. The search is only unarchived
          if it matches, otherwise `404`.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      - name: startDate
        in: query
        description: |
          ISO 8601 date or date-time lower bound for `createdAt`. The search is only unarchived
          if it was created on or after it, otherwise `404`. A value JavaScript's `Date`
          cannot parse is refused with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      - name: endDate
        in: query
        description: |
          ISO 8601 date or date-time upper bound for `createdAt`. The search is only unarchived
          if it was created on or before it, otherwise `404`. A value JavaScript's `Date`
          cannot parse is refused with `400`.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}
      responses:
        '200':
          description: Search unarchived successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - id
                - status
                - unarchivedBy
                - unarchivedAt
                - meta
                properties:
                  id:
                    type: string
                    format: objectId
                    description: Unique identifier of the unarchived search.
                    example: 65f1c0a4e2b9c4d8f3a1b2c3
                  status:
                    type: string
                    enum:
                    - unarchived
                    description: Resulting status of the search after the operation.
                    example: unarchived
                  unarchivedBy:
                    type: string
                    format: objectId
                    description: User ID of the user who unarchived the search.
                    example: 65f1c0a4e2b9c4d8f3a1b2c4
                  unarchivedAt:
                    type: string
                    format: date-time
                    description: Timestamp when the search was unarchived.
                    example: '2026-05-10T12:34:56.789Z'
                  meta:
                    type: object
                    additionalProperties: false
                    required:
                    - timestamp
                    - duration
                    properties:
                      requestId:
                        type: string
                        description: Server-assigned request identifier for tracing. Omitted when not available.
                        example: req_8f3a1b2c
                      timestamp:
                        type: string
                        format: date-time
                        description: Server timestamp when the response was produced.
                        example: '2026-05-10T12:34:56.789Z'
                      duration:
                        type: integer
                        description: Time taken to process the request, in milliseconds.
                        example: 42
        '400':
          description: |
            Invalid request. `VALIDATION_ERROR` naming `params.searchId` when `searchId` is not
            a 24-character hex id. `HTTP_BAD_REQUEST` when a query filter is invalid: `shared`
            is not a boolean, `startDate` / `endDate` cannot be parsed, or `search` is over 1000
            characters or contains HTML markup. A search that is not
            archived is `404`, not `400`.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: |
            Missing or invalid bearer token (`HTTP_UNAUTHORIZED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            OAuth access token without the `semantic:write` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            No archived search matched (`HTTP_NOT_FOUND`, "Search Id not found or no unarchive
            permission"): the id does not exist in the caller's org, the caller neither owns
            the search nor has it shared with them, it is not archived, it was deleted, or a
            `shared`, `startDate` or `endDate` query filter does not match it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Unexpected server error while unarchiving the search.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents:
    get:
      tags:
      - Agents
      summary: List agents
      description: |
        Retrieve a paginated list of agents available to the authenticated user.

        **Overview**

        Returns agents accessible through direct, team, or org-level permissions.
        Search is performed across agent name, description, and tags. Sorting and
        pagination are applied by the AI backend and the resulting envelope is
        forwarded unchanged by the Node gateway.

        **Gateway contract**

        The Node route supports only these query params: `page`, `limit`, `search`,
        `sort_by`, and `sort_order`.

        The Python backend also understands `isDeleted`, but this gateway route
        does not forward it, so it is not part of the public API contract here.
        Any other query parameter is ignored, not refused.
      operationId: listAgents
      security:
      - bearerAuth: []
      - oauth2:
        - agent:read
      parameters:
      - in: query
        name: page
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        description: 1-based page number.
      - in: query
        name: limit
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
        description: Maximum number of agents to return in the current page.
      - in: query
        name: search
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 1000
          pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]|<[^>]{0,10000}>))[\s\S]*?\S
        description: |
          Case-insensitive search across agent name, description, and tags.
          Leading/trailing whitespace is trimmed; a blank value is refused with
          `VALIDATION_ERROR`, and so is a printf-style format specifier (`%s`,
          `%x`, ...). Markup (HTML tags, `javascript:`, event handlers) is
          refused with `HTTP_BAD_REQUEST` by the sanitizer every route runs.
      - in: query
        name: sort_by
        required: false
        schema:
          type: string
          minLength: 1
          maxLength: 100
          pattern: \S
          default: updatedAtTimestamp
        description: |
          Backend sort field. Leading/trailing whitespace is trimmed and a blank
          value is refused. Any other value is accepted. Common value is
          `updatedAtTimestamp`.
      - in: query
        name: sort_order
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        description: Sort direction.
      responses:
        '200':
          description: Paginated list of accessible agents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentListResponse'
              examples:
                success:
                  summary: Example paginated response
                  value:
                    success: true
                    agents:
                    - _id: agentInstances/11111111-2222-3333-4444-555555555555
                      _key: 11111111-2222-3333-4444-555555555555
                      _rev: _exampleRev---
                      createdAtTimestamp: 1779792574728
                      createdBy: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
                      description: AI agent for customer support workflows
                      isActive: true
                      isDeleted: false
                      isServiceAccount: false
                      models:
                      - 99999999-8888-7777-6666-555555555555_gpt-5.6-luna
                      name: Customer Support Agent
                      startMessage: Hello! How can I help you today?
                      systemPrompt: You are a helpful assistant.
                      tags: []
                      updatedAtTimestamp: 1779792574728
                      shareWithOrg: false
                      toolsets: []
                      knowledge: []
                      can_view: true
                      can_share: true
                      can_edit: true
                      can_delete: true
                      user_role: OWNER
                      access_type: INDIVIDUAL
                    pagination:
                      currentPage: 1
                      limit: 20
                      totalItems: 2
                      totalPages: 1
                      hasNext: false
                      hasPrev: false
        '400':
          description: |
            Validation failed for one or more query params (`VALIDATION_ERROR`), or
            `search` carries markup (`HTTP_BAD_REQUEST`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The OAuth access token lacks the `agent:read` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Unexpected gateway failure. When the AI backend
            answers with an error, the route still answers `200` with an empty list.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/create:
    post:
      tags:
      - Agents
      summary: Create agent
      description: |
        Create a new custom AI agent.

        **Overview:**
        Agents are specialized AI assistants configured for specific tasks.
        They can have custom system prompts, access to specific tools, and
        be limited to certain knowledge bases.

        **Agent Configuration:**
        - **System prompt:** Instructions that define agent behavior
        - **Tools:** Capabilities like web search, code execution, etc.
        - **Knowledge bases:** Data sources the agent can access
        - **Model config:** AI model settings (temperature, max tokens)

        **Use Cases:**
        - Customer support bot with product knowledge
        - Code review assistant with repository access
        - HR assistant with policy documents
      operationId: createAgent
      security:
      - bearerAuth: []
      - oauth2:
        - agent:write
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreateRequest'
      responses:
        '201':
          description: Agent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCreateResponse'
        '400':
          description: |
            Invalid agent configuration. The gateway validator answers
            `VALIDATION_ERROR` (missing or blank `name`, a `models` list without a
            reasoning entry, an unregistered toolset name, two MCP servers of one
            type, wrong types, ...). Rules the AI backend applies answer
            `HTTP_BAD_REQUEST`.

            `serviceAccountUserId` without `isServiceAccount` is refused (`VALIDATION_ERROR` on
            `serviceAccountUserId`: `Only a service agent searches as a service account. Set
            isServiceAccount, or leave the binding out.`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid token (`HTTP_UNAUTHORIZED`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The OAuth access token lacks the `agent:write` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The AI backend failed to save the agent.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}:
    get:
      tags:
      - Agents
      summary: Get agent
      description: |
        Retrieve agent details by its unique key.

        **Gateway not-found behavior:**
        Unknown `agentKey`, lookup after soft-delete, and other AI-backend failures
        that return 404 from the Python query service are surfaced by the Node
        gateway as **HTTP 404** with an `ErrorResponse` body. An agent the caller
        has no access to (another user's agent that is not shared) is also a
        `404`, not a `403`.

        The route reads no query parameter; any that is sent is ignored.
      operationId: getAgent
      security:
      - bearerAuth: []
      - oauth2:
        - agent:read
      parameters:
      - name: agentKey
        in: path
        required: true
        description: Unique agent identifier
        schema:
          type: string
          minLength: 1
        example: customer-support-agent
      responses:
        '200':
          description: Agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAgentResponse'
        '401':
          description: Missing or invalid bearer token (e.g. `No token provided`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — insufficient OAuth scope (`agent:read` required)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: |
            Gateway validation failure (non-empty `agentKey` path param), an
            `agentKey` that is not safe to forward (for example one that decodes
            to a `%`), or missing organization/user context on the authenticated
            request.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Agent not found, inaccessible, or previously deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Unexpected AI-backend or gateway failure.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: AI query service unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - Agents
      summary: Update agent
      description: |
        Apply a partial update to an existing agent configuration.

        **Gateway contract**

        The Node gateway validates the request body via Zod middleware before
        forwarding to the Python agent service. The `agentKey` path param and
        the request body are both validated. Query parameters are ignored by
        the controller, and body fields the validator does not know are dropped
        rather than refused. The body may be omitted: an empty update succeeds
        and changes nothing.

        **Update semantics**

        Only fields present in the request body are updated. `models` may be
        omitted (the agent's existing models are kept), set to an empty array
        (clears the agent's models so it falls back to the organization's
        default LLM at chat time), or set to a non-empty array. When a
        non-empty array is provided, the gateway Zod middleware requires at
        least one object entry with `isReasoning: true`.

        **Permissions**

        The authenticated user must have `can_edit` on the agent (typically the
        owner). Service-account and `shareWithOrg` transitions follow additional
        Python business rules.

        **Success response**

        Returns a lightweight success envelope only. Use
        `GET /agents/{agentKey}` to read the persisted agent after an update.
      operationId: updateAgent
      security:
      - bearerAuth: []
      - oauth2:
        - agent:write
      parameters:
      - name: agentKey
        in: path
        required: true
        description: Unique agent identifier
        schema:
          type: string
          minLength: 1
        example: customer-support-agent
      requestBody:
        required: false
        description: Partial agent configuration fields to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentUpdateRequest'
      responses:
        '200':
          description: Agent updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentUpdateResponse'
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            `HTTP_FORBIDDEN`: the OAuth access token lacks the `agent:write` scope,
            or the caller can see the agent (for example one shared with the
            organization) but is not its owner, so may not edit it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: |
            `VALIDATION_ERROR` from the gateway validator: a blank or overlong
            `name`, a non-empty `models` list without a reasoning entry, an
            unregistered toolset name, two MCP servers of one type, or other
            schema violations. `HTTP_BAD_REQUEST` for an `agentKey` that is not
            safe to forward, and from the AI backend's rules, for example turning
            a service-account agent back into a regular one
            (`isServiceAccount: false`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Agent not found, deleted, or not visible to the caller (another user's
            agent that is not shared).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Unexpected AI-backend or gateway failure.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Agents
      summary: Delete agent
      description: |
        Soft-delete an agent (tombstone) in the graph database.

        **Overview:**
        The Python query service marks the agent instance deleted inside a transaction.
        List and search endpoints exclude tombstoned agents. Toolsets, tools, and
        knowledge linked to the agent are not removed by this call.

        **Permissions:**
        Only the agent owner may delete (`can_delete` on the permission check).

        **Warning:**
        All conversations with this agent will become inaccessible.

        **Gateway not-found behavior:**
        Unknown `agentKey`, deleting an already-deleted agent, deleting another
        user's agent that is not shared with the caller, and `GET /agents/{agentKey}`
        after delete return **HTTP 404** with an `ErrorResponse` body.

        The route reads neither a query nor a body; anything sent is ignored.
      operationId: deleteAgent
      security:
      - bearerAuth: []
      - oauth2:
        - agent:write
      parameters:
      - name: agentKey
        in: path
        required: true
        description: Unique agent identifier (gateway Zod requires non-empty string).
        schema:
          type: string
          minLength: 1
        example: customer-support-agent
      responses:
        '200':
          description: Agent soft-deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentDeleteResponse'
        '400':
          description: |
            `HTTP_BAD_REQUEST`: the `agentKey` path segment is not safe to forward
            (for example one that decodes to a `%`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid bearer token (e.g. `No token provided`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            `HTTP_FORBIDDEN`: the OAuth access token lacks the `agent:write` scope,
            or the caller can see the agent (for example one shared with the
            organization) but is not its owner.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Agent not found, inaccessible, or already deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Unexpected AI-backend or gateway failure.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/conversations/show/archives:
    get:
      tags:
      - Agents
      summary: List archived agent conversations grouped by agent
      description: |
        Returns archived agent conversations for the current user, grouped by
        `agentKey`, with pagination over agent groups. Excludes conversations
        whose agent was soft-deleted upstream.
      operationId: listAgentArchivedConversationsGrouped
      security:
      - bearerAuth: []
      - oauth2:
        - agent:read
      parameters:
      - name: agentPage
        in: query
        required: false
        description: |
          1-based page over agent groups. Values below 1 are read as 1 and a
          non-numeric value as the default; neither is refused.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: agentLimit
        in: query
        required: false
        description: |
          Agent groups per page. Values are clamped to 1..100 and a non-numeric
          value is read as the default; neither is refused. Each group carries at
          most 5 conversations.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 5
      responses:
        '200':
          description: Grouped archived conversations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentArchivedGroupsResponse'
        '400':
          $ref: '#/components/responses/XssRejected'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The access token lacks the `agent:read` OAuth scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/show/archives:
    get:
      tags:
      - Agents
      summary: List archived conversations for an agent
      description: |
        Paginated list of the caller's archived conversations for the given agent
        key. The `agentKey` is matched against the stored conversations only; the
        agent itself is not looked up.

        The query is strict: a parameter not listed here is refused with `400`
        (`VALIDATION_ERROR` on `query`, "These fields aren't accepted here").
      operationId: listAgentConversationArchives
      security:
      - bearerAuth: []
      - oauth2:
        - agent:read
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: |
          1-based page number. A value below 1 or one that is not a number is
          read as `1`; neither is refused.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: |
          Page size. A value outside 1..100 or one that is not a number is read
          as `20`; neither is refused.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: sortBy
        in: query
        description: |
          Sort field. Supported values are `createdAt`, `lastActivityAt` and
          `title`; any other value is accepted and ignored (the list is then
          sorted by `lastActivityAt`).
        schema:
          type: string
      - name: sortOrder
        in: query
        description: |
          Sort direction, `asc` or `desc`; any other value is accepted and
          ignored (descending order).
        schema:
          type: string
      - name: search
        in: query
        description: |
          Case-insensitive search over the conversation title and message
          content. A printf-style format specifier (`%s`, `%x`, ...) is refused
          with `VALIDATION_ERROR`; markup (HTML tags, `javascript:`, event
          handlers) is refused with `HTTP_BAD_REQUEST` by the sanitizer every
          route runs.
        schema:
          type: string
          maxLength: 1000
          pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]|<[^>]{0,10000}>))
      - name: startDate
        in: query
        description: |
          Inclusive lower bound on `createdAt`, as an ISO 8601 date or
          date-time. The validator accepts any string JavaScript `Date` can
          parse (so also forms like `May 1 2026` or `2026/05/01`); one it
          cannot parse returns HTTP 400. An empty value is read as not sent.
        schema:
          type: string
          pattern: ^$|^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$
      - name: endDate
        in: query
        description: |
          Inclusive upper bound on `createdAt`, as an ISO 8601 date or
          date-time. The validator accepts any string JavaScript `Date` can
          parse (so also forms like `May 1 2026` or `2026/05/01`); one it
          cannot parse returns HTTP 400. An empty value is read as not sent.
        schema:
          type: string
          pattern: ^$|^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$
      responses:
        '200':
          description: Archived conversations for the agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentArchivedConversationListResponse'
        '400':
          description: |
            `VALIDATION_ERROR` for an unknown query parameter, a date that does not
            parse, an overlong `search` or one with a format specifier;
            `HTTP_BAD_REQUEST` for markup in `search` or an `agentKey` that is not
            safe to forward.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The OAuth access token lacks the `agent:read` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/attachments/upload:
    post:
      tags:
      - Agents
      summary: Upload agent chat attachments
      description: |
        Multipart upload of chat attachment files (the MIME types listed on `files`) for
        agent chat: up to 10 files, 5 MiB each. Proxies to the AI backend. Optional
        `conversationId` associates uploads with an existing agent thread.
      operationId: uploadAgentConversationChatAttachments
      security:
      - bearerAuth: []
      - oauth2:
        - agent:execute
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        description: Multipart form with attachment files and optional `conversationId`.
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - files
              properties:
                conversationId:
                  type: string
                  pattern: ^$|^[0-9a-fA-F]{24}$
                  description: |
                    Optional existing agent conversation id. Empty string is treated as unset; any non-empty value must be a 24-character ObjectId.
                files:
                  type: array
                  minItems: 1
                  maxItems: 10
                  description: |
                    One or more files; field name must be `files`. Accepted MIME types: `application/pdf`, `image/jpeg`, `image/jpg`, `image/png`, `text/plain`, `text/markdown`, `text/mdx`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `text/csv`, `text/tab-separated-values`. Max 5 MiB each.
                  items:
                    type: string
                    format: binary
                    x-speakeasy-name-override: File
      responses:
        '200':
          description: |
            Success. The gateway proxies the AI-backend JSON envelope after transforming the multipart upload into the backend attachment payload.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatAttachmentUploadResponse'
        '400':
          description: |
            Invalid `conversationId` (`VALIDATION_ERROR`), no file part, or an unsupported MIME type (`HTTP_BAD_REQUEST`). The `agentKey` is not looked up. Multer's own rejections are not a 400: see 500.

            An image that is not a valid JPEG, PNG or WebP (`<name> is not a valid JPEG, PNG or WebP
            image`), or one over 50 megapixels (`<name> is too large to attach: images can be at most 50
            megapixels`), is refused too (`HTTP_BAD_REQUEST`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: |
            A PDF that could not be read within the upload's 50-second budget, or
            whose parse ran out of memory, is not attached (`<name> is too large or complex to read
            right now, so it wasn't attached. ...`). Only that upload fails.
          content:
            application/json:
              schema:
                type: object
                required:
                - detail
                properties:
                  detail:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing `agent:execute` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Gateway fallback when the upstream call does not return a status (implementation default). Also returned (`INTERNAL_ERROR`) for every Multer rejection, which is not mapped to a 400: more than 10 files, a file over 5 MiB, or a file part not named `files`.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/attachments/{recordId}:
    delete:
      tags:
      - Agents
      summary: Delete an agent chat attachment
      description: |
        Deletes a previously uploaded attachment by proxying `DELETE` to the query service
        (`/api/v1/chat/attachments/{recordId}`). The Node handler always ends the response **without
        a JSON body** on success (empty body); the **status code** is the upstream status, or **204**
        if none is returned.

        On validation failure in the gateway (invalid / blank path params), the response is **400**
        with a small JSON error object. Same fire-and-forget semantics as
        `DELETE /conversations/attachments/{recordId}` on the client.
      operationId: deleteAgentConversationChatAttachment
      security:
      - bearerAuth: []
      - oauth2:
        - agent:execute
      parameters:
      - name: agentKey
        in: path
        required: true
        description: Agent key path parameter. Must be non-empty.
        schema:
          type: string
          minLength: 1
      - name: recordId
        in: path
        required: true
        description: Attachment record id (from the upload response). Must be non-blank after trim.
        schema:
          type: string
          minLength: 1
          maxLength: 256
      responses:
        '204':
          description: Success with no content (typical when upstream returns 204).
        '400':
          description: |
            Invalid path params: a `recordId` longer than 256 characters
            (`VALIDATION_ERROR`), or a path segment that is blank or decodes to
            a `%` or a control character (`HTTP_BAD_REQUEST`).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Missing `agent:execute` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            The record exists but is not a chat attachment, or is not owned by
            the caller (for example another member's upload). Forwarded from
            the query service with an empty body. An id that names no record
            answers 204.
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          description: |
            Other status codes are forwarded from the query service (e.g. 404) with an **empty** response body from this route.
  /agents/{agentKey}/conversations/stream:
    post:
      tags:
      - Agents
      summary: Create agent conversation with streaming response
      description: |
        Start a new conversation with the specified agent and stream the AI
        response as Server-Sent Events (SSE). The first user message is saved
        and forwarded to the upstream agent backend; subsequent tokens, tool
        calls, and lifecycle events are emitted on the open SSE connection.

        AG-UI is the sole wire protocol. The request must include
        `chatMode: quick`; see `AgentStreamSSEEvent` for the event vocabulary.
      operationId: streamAgentConversation
      security:
      - bearerAuth: []
      - oauth2:
        - agent:execute
      parameters:
      - name: agentKey
        in: path
        required: true
        description: Stable key identifying the agent that owns this conversation.
        schema:
          type: string
          minLength: 1
      requestBody:
        required: true
        description: Initial turn payload for the new agent conversation stream.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentStreamCreateConversationRequest'
      responses:
        '200':
          description: |
            SSE stream (text/event-stream). The conversation is saved and
            announced (`CUSTOM` `conversation_created`) before the agent is
            looked up, so an unknown `agentKey` or any later failure still
            answers 200 and ends the stream with a `RUN_ERROR` frame.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AgentStreamSSEEvent'
        '400':
          description: |
            Invalid path or body, answered before the stream opens: field
            validation failures answer `VALIDATION_ERROR`; markup in any string
            field (checked by this route after authentication; the app-wide filter
            skips POST and PUT under `/agents/`) answers
            `HTTP_BAD_REQUEST`.

            A `previousConversations` field holding anything but an empty list (`HTTP_BAD_REQUEST`,
            `previousConversations is not accepted. Conversation history is read from the stored
            conversation: create the conversation, then send follow-up questions to its messages
            endpoint.`). Checked after authentication and before the body validator; an empty list is
            dropped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The access token lacks the `agent:execute` OAuth scope, or, with a `projectId`, lacks `project:read`. Returned before the SSE stream opens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The `projectId` names a project that does not exist or that the caller cannot see (`HTTP_NOT_FOUND`). Returned before the SSE stream opens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The `projectId` names an archived project (`HTTP_CONFLICT`); unarchive it to start chats in it. Returned before the SSE stream opens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/{conversationId}/messages/stream:
    post:
      tags:
      - Agents
      summary: Add message to agent conversation with streaming response
      description: |
        Append a user message to an existing agent conversation and stream the
        assistant reply over SSE.

        AG-UI is the sole wire protocol. The request must include
        `chatMode: quick`; see `AgentMessageStreamSSEEvent` for the event
        vocabulary.
      operationId: streamAgentConversationMessage
      security:
      - bearerAuth: []
      - oauth2:
        - agent:execute
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        description: Follow-up message payload for the agent conversation stream.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentAddMessageStreamRequest'
      responses:
        '200':
          description: |
            SSE stream (text/event-stream). The stream opens before the
            conversation is looked up, so a conversation that does not exist,
            belongs to another user or to another agent also answers 200: the
            stream carries one `RUN_ERROR` frame with `code: internal_error`
            and ends. There is no 404.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AgentMessageStreamSSEEvent'
        '400':
          description: |
            Invalid path or body, answered before the stream opens: field
            validation failures answer `VALIDATION_ERROR`; markup in any string
            field (checked by this route after authentication; the app-wide filter
            skips POST and PUT under `/agents/`) answers
            `HTTP_BAD_REQUEST`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The access token lacks the `agent:execute` OAuth scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/{conversationId}/message/{messageId}/regenerate:
    post:
      tags:
      - Agents
      summary: Regenerate agent conversation message
      description: |
        Regenerate the AI response for a specific message in an agent
        conversation and stream the new answer over Server-Sent Events.

        **Constraints:**

        - Only the last message in the conversation can be regenerated.
        - The target message must be of type `bot_response`.

        **Request body:**

        `chatMode: quick` is required. Other fields are optional and reuse
        the original model/context when omitted. The body supports:
        - `query` and `attachments` (an edited question and its files, as on the assistant endpoint)
        - `filters`
        - `chatMode`
        - `modelKey`
        - `modelName`
        - `modelFriendlyName`
        - `timezone`
        - `currentTime`
        - `tools`
        - `protocol`
        - `agentCapabilities`

        **Streaming behavior:**

        The response is delivered as an AG-UI `text/event-stream`. Stable
        outcomes are `RUN_FINISHED` and `RUN_ERROR`; see
        `AgentRegenerateSSEEvent`.

        Additional agent/tool lifecycle events may be forwarded by the
        backend and should be treated as informational updates.

        Validation failures on params/body are returned as normal HTTP `400`
        responses before the stream starts. Valid-shape requests that fail
        conversation lookup or regenerate rules are reported as
        `RUN_ERROR` events after stream initialization.
      operationId: regenerateAgentConversationMessage
      security:
      - bearerAuth: []
      - oauth2:
        - agent:execute
      parameters:
      - name: agentKey
        in: path
        required: true
        description: Stable key identifying the agent that owns this conversation.
        schema:
          type: string
          minLength: 1
      - name: conversationId
        in: path
        required: true
        description: ID of the agent conversation containing the target message.
        schema:
          type: string
          format: objectId
      - name: messageId
        in: path
        required: true
        description: ID of the bot-response message to regenerate.
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        description: |
          Regeneration payload requiring `chatMode: quick`.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRegenerateRequest'
      responses:
        '200':
          description: |
            SSE stream established.

            Stable event names:
            - `RUN_FINISHED` — `{ type, result }`, where `result` contains the
              updated conversation and metadata
            - `RUN_ERROR` — `{ type, message, code? }`, reporting lookup,
              authorization, or regenerate-rule failures

            Forwarded lifecycle and child-run events may include `runId`,
            `threadId`, and `parentRunId`. Additional backend-defined
            agent/tool events may be emitted.
            Clients should ignore unknown event names.

            Two refusals about `answers` arrive the same way: `Answers can only replace the answers to a
            question card.` and `An edit cannot also replace the answers to a question card.`
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/AgentRegenerateSSEEvent'
        '400':
          description: |
            Validation failed for path parameters or request body. Common
            causes include invalid ObjectId formats, empty strings for fields
            that require content, malformed `filters`, invalid `tools`
            entries, or `currentTime` values that are not ISO 8601 datetimes
            with offset information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The access token lacks the `agent:execute` OAuth scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/{conversationId}/message/{messageId}/fork:
    post:
      tags:
      - Agents
      summary: Fork agent conversation from a message
      description: |
        Copy this agent conversation into a new private chat owned by the
        caller, including every message up to and including `messageId`. The
        original conversation is left unchanged.

        Only the owner of the conversation can fork it; anyone else gets 404.
      operationId: forkAgentConversation
      security:
      - bearerAuth: []
      - oauth2:
        - agent:execute
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
          minLength: 1
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      - name: messageId
        in: path
        required: true
        description: Inclusive last message to copy into the new chat
        schema:
          type: string
          format: objectId
      responses:
        '201':
          description: Forked conversation created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForkConversationResponse'
        '400':
          description: Invalid conversation, message or agent id (`VALIDATION_ERROR`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - token is missing the `agent:execute` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            `Conversation not found` when the conversation does not exist, is deleted, is not a
            conversation with this agent, or is not the caller's own (an archived one can be
            forked); `Message not found` when `messageId` is not a message of that conversation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error, for example when an artifact of the conversation could not
            be copied into the fork (`Could not copy <n> artifact(s) into the fork`); no fork is
            created then.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/{conversationId}/cancel:
    post:
      tags:
      - Agents
      summary: Cancel an in-flight agent chat stream
      description: |
        Cooperatively stop a `POST /agents/{agentKey}/conversations/stream`
        or `.../messages/stream` run that is still generating, using the
        `runId` sent when that stream started.

        Same synchronous JSON ack contract as the assistant
        `POST /conversations/{conversationId}/cancel` — both forward to the
        same backend cancellation endpoint, since the run registry is keyed
        by `runId` alone.

        `cancelled` reports whether a stop request was issued, not whether a
        run was actually stopped. With the default shared (key-value backed)
        run registry, a `runId` that the answering worker does not hold is
        published for whichever worker owns it, and the answer is
        `{ cancelled: true }` even when the run already finished or was
        never registered. `{ cancelled: false }` is returned for such a
        `runId` only when the registry is in-process, or when the stop
        request could not be published.

        `runId` must belong to a run started on THIS `conversationId` — a
        `runId` that exists but was registered under a different
        conversation (even one owned by the same caller) is rejected with
        `403`, same as a `runId` owned by a different user/org.
      operationId: cancelAgentConversationStream
      security:
      - bearerAuth: []
      - oauth2:
        - agent:execute
      parameters:
      - name: agentKey
        in: path
        required: true
        description: Stable key identifying the agent that owns this conversation.
        schema:
          type: string
          minLength: 1
      - name: conversationId
        in: path
        required: true
        description: ID of the agent conversation to cancel a run for.
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - runId
              properties:
                runId:
                  type: string
                  format: uuid
                  pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                  description: |
                    The `runId` sent when the stream was started. Anything but a
                    UUID string is refused with `VALIDATION_ERROR`.
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - runId
              properties:
                runId:
                  type: string
                  format: uuid
                  pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
                  description: |
                    The `runId` sent when the stream was started. Anything but a
                    UUID string is refused with `VALIDATION_ERROR`.
      responses:
        '200':
          description: Cancellation requested, or the run had already finished.
          content:
            application/json:
              schema:
                type: object
                required:
                - cancelled
                properties:
                  cancelled:
                    type: boolean
                    description: '`true` when a stop request was issued for `runId`; `false` when the run is unknown to an in-process registry or the request could not be published.'
        '400':
          description: Missing or malformed `runId`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The access token lacks the `agent:execute` OAuth scope, or `runId` belongs to a run still in flight that was registered under a different user, org, or conversation than this request. Once that run has ended its `runId` is unknown and the answer is 200.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conversation not found or unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/{conversationId}/message/{messageId}/feedback:
    post:
      tags:
      - Agents
      summary: Submit feedback for an agent message
      description: |
        Append structured feedback to a bot-response message in an agent
        conversation. Uses the same request body shape as
        `updateMessageFeedback` (helpfulness, categories, comments). Feedback
        can only be submitted on `bot_response` messages.
      operationId: updateAgentConversationMessageFeedback
      security:
      - bearerAuth: []
      - oauth2:
        - agent:execute
      parameters:
      - name: agentKey
        in: path
        required: true
        description: Unique agent identifier (gateway Zod requires non-empty string).
        schema:
          type: string
          minLength: 1
      - name: conversationId
        in: path
        required: true
        description: Unique conversation identifier.
        schema:
          type: string
          format: objectId
      - name: messageId
        in: path
        required: true
        description: Identifier of the bot-response message being rated.
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        description: Feedback payload for the agent message.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageFeedbackSubmitRequest'
      responses:
        '200':
          description: Feedback stored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageFeedbackUpdateResponse'
        '400':
          description: |
            Invalid request. Possible causes:

            - Feedback target is not a `bot_response` message.
            - A `categories` value is not in the allowed list.
            - `conversationId` or `messageId` is not a valid ObjectId.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The access token lacks the `agent:execute` OAuth scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Conversation or message not found: the conversation does not exist,
            is deleted, belongs to another user or to another agent, or the
            message is not in it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Persistence layer failed to append the feedback entry.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/{conversationId}/messages:
    post:
      tags:
      - Agents
      summary: Add message to agent conversation (non-streaming)
      description: |
        Ask a follow-up in an existing agent conversation and wait for the
        complete answer. The JSON counterpart of
        `POST /agents/{agentKey}/conversations/{conversationId}/messages/stream`.

        **How a turn runs**

        1. The user's message is saved (in its own short transaction on a
           replica set).
        2. The AI backend runs the same agent-loop pipeline as the `/stream`
           route and returns only its final result. No transaction is held
           during this call, and the call is never retried.
        3. The answer, citations and status are saved exactly as the
           streaming route saves them, and the updated conversation is
           returned.

        Every failure after step 1 is persisted: the conversation ends with
        status `Failed`, a `failReason`, and an `error` message, and the
        response carries `X-Conversation-Id` so the caller can fetch it.
        A 4xx from the AI backend (for example no model configured) keeps
        its status and user-facing message; other failures return 500 with
        a generic message.

        The response arrives only when the whole answer is ready, which can
        take minutes for agent runs. Allow a generous client and proxy
        timeout, or use the `/stream` variant for interactive clients.
      operationId: addAgentConversationMessage
      security:
      - bearerAuth: []
      - oauth2:
        - agent:execute
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        description: |
          The follow-up question, with optional scope, model and tool overrides. A `query` that
          holds markup or a printf-style format specifier is refused with `400`
          `HTTP_BAD_REQUEST`, and so is one of only whitespace ("Query is required").
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentAddMessageRequest'
      responses:
        '200':
          description: The conversation with the new question and answer.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAddMessageResponse'
        '400':
          description: |
            Invalid request. Field validation failures answer `VALIDATION_ERROR`
            (`query` missing, empty or over 100,000 characters, a malformed id,
            an unknown enum value, an incomplete `appliedFilters` node, ...).
            A `query` holding a printf-style format specifier (`%s`, `%x`, ...)
            and any string field holding markup (HTML tags, `javascript:`, event
            handlers) answer `HTTP_BAD_REQUEST` before the message is saved;
            this route checks markup itself, after authentication, because the
            app-wide filter skips POST and PUT under `/agents/`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — valid bearer token required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — the token lacks the `agent:execute` OAuth scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Conversation not found — it does not exist, belongs to another
            user, is of the other type (assistant vs agent), or belongs to a
            different agent; refused before the message is saved. Also
            returned when the AI backend has no agent with this key or the
            caller has no access to it (an agent not shared with a member is
            not a 403): that turn fails after the user message is saved, the
            conversation is kept with status `Failed`, and `X-Conversation-Id`
            names it.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: The request is larger than the selected model accepts.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '422':
          description: The model provider's content filter blocked the request.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '424':
          description: |
            No usable LLM — none is configured for the organization, the
            selected one could not start, or its provider rejected the API
            key or could not find the model. The message says what to fix.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: The model provider is rate limiting or out of quota.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '500':
          description: |
            The answer failed (the AI service returned no answer, or it could
            not be saved). The conversation is kept with
            status `Failed` and an `error` message.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: |
            The AI service could not be reached (for example, it is still
            starting). The conversation is marked `Failed`; that save is best
            effort, so if it fails the conversation keeps its previous status.
            Sending the message again may repeat work the AI service had started.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: |
            The AI service did not answer in time. The conversation is marked
            `Failed`; that save is best effort, so if it fails the conversation
            keeps its previous status. The AI service may have started the turn,
            so sending the message again may repeat work it had started.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/{conversationId}/archive:
    post:
      tags:
      - Agents
      summary: Archive an agent conversation
      description: |
        Marks the conversation as archived for the authenticated owner. The route
        reads no query parameter and no body; anything sent is ignored.
      operationId: archiveAgentConversation
      security:
      - bearerAuth: []
      - oauth2:
        - agent:write
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      responses:
        '200':
          description: Conversation archived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConversationArchiveResponse'
        '400':
          description: |
            `VALIDATION_ERROR` for a malformed `conversationId`, `HTTP_BAD_REQUEST`
            for an `agentKey` that is not safe to forward or a conversation that
            is already archived.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The OAuth access token lacks the `agent:write` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            No conversation of the caller with this id under this `agentKey`
            (missing, another user's, another agent's, or deleted).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/{conversationId}/unarchive:
    post:
      tags:
      - Agents
      summary: Unarchive an agent conversation
      description: |
        Restores an archived agent conversation to the active list. The route
        reads no query parameter and no body; anything sent is ignored.
      operationId: unarchiveAgentConversation
      security:
      - bearerAuth: []
      - oauth2:
        - agent:write
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      responses:
        '200':
          description: Conversation unarchived
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConversationUnarchiveResponse'
        '400':
          description: |
            `VALIDATION_ERROR` for a malformed `conversationId`, `HTTP_BAD_REQUEST`
            for an `agentKey` that is not safe to forward or a conversation that
            is not archived.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The OAuth access token lacks the `agent:write` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            No conversation of the caller with this id under this `agentKey`
            (missing, another user's, another agent's, or deleted).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/{conversationId}/title:
    patch:
      tags:
      - Agents
      summary: Update agent conversation title
      description: |
        Updates the display title for an agent conversation owned by the caller.

        The controller looks up the conversation by `_id`, `orgId`, `userId`,
        `agentKey`, and `isDeleted: false`.

        The request body uses the shared title validator (`1..200` chars) and the
        title is trimmed before it is saved; a whitespace-only title is refused
        with `400` (`VALIDATION_ERROR`). Unknown body fields are dropped and query
        parameters are ignored.
      operationId: updateAgentConversationTitle
      security:
      - bearerAuth: []
      - oauth2:
        - agent:write
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      requestBody:
        required: true
        description: |
          New title for the agent conversation.

          The server trims the provided string before saving it.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversationTitleUpdateRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ConversationTitleUpdateRequest'
      responses:
        '200':
          description: Title updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConversationTitleUpdateResponse'
        '400':
          description: |
            Invalid path or body input.

            `VALIDATION_ERROR` for a malformed `conversationId` or a missing,
            blank, overlong or non-string `title`; `HTTP_BAD_REQUEST` for an
            `agentKey` that is not safe to forward.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The OAuth access token lacks the `agent:write` scope (`HTTP_FORBIDDEN`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Agent conversation not found for the authenticated user, organization,
            and agent scope, or the conversation is soft-deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations/{conversationId}:
    delete:
      tags:
      - Agents
      summary: Delete an agent conversation
      description: |
        Soft-deletes an agent conversation owned by the authenticated user.

        The controller scopes the lookup by `_id`, `orgId`, `userId`, and
        `agentKey`. If no matching writable conversation is found, the route is
        intentionally a no-op and still returns HTTP 200 with `conversation: null`.

        This makes the operation idempotent:

        - deleting a nonexistent conversation returns success with `null`
        - deleting through a different `agentKey` returns success with `null`
        - deleting an already deleted conversation returns success with `null`

        **Artifacts:** before the conversation is marked deleted, every artifact
        the caller created in it is deleted for good (every version and stored
        file). Artifacts another participant created stay theirs. If the cleanup
        cannot be done the conversation is left in place and the error is
        returned (for example 503); repeating the request finishes it.
      operationId: deleteAgentConversationById
      security:
      - bearerAuth: []
      - oauth2:
        - agent:write
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      responses:
        '200':
          description: Conversation deleted or no-op delete completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConversationDeleteResponse'
        '400':
          description: |
            Invalid path input

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The access token lacks the `agent:write` OAuth scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while deleting the agent conversation.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Agents
      summary: Get agent conversation by ID
      description: |
        Returns the conversation with paginated/sorted messages and filter metadata.

        **Message Pagination:**

        Messages are paginated newest-first: `page=1` returns the most recent
        batch. Increment `page` to load older batches (used by the infinite-scroll
        "load older messages" feature).

        - `page`: Page number (default: 1)
        - `limit`: Messages per page (default: 20, max: 100)
      operationId: getAgentConversationById
      security:
      - bearerAuth: []
      - oauth2:
        - agent:read
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      - name: conversationId
        in: path
        required: true
        schema:
          type: string
          format: objectId
      - name: page
        in: query
        description: Page number for message pagination (1 = most recent batch)
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Number of messages per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: sortBy
        in: query
        description: Field to sort messages by
        schema:
          type: string
          enum:
          - createdAt
          - messageType
          - content
          default: createdAt
      - name: sortOrder
        in: query
        description: |
          Sort direction. `asc` sorts ascending; any other value, including
          an unrecognised one, is read as `desc` and is not refused.
        schema:
          type: string
          default: desc
      - name: startDate
        in: query
        description: |
          Filter messages created on or after this date, as an ISO 8601 date
          or date-time. The validator accepts any string JavaScript `Date` can
          parse (so also forms like `May 1 2020` or `2999/01/01`); one it
          cannot parse returns HTTP 400. An empty value is read as not sent.
        schema:
          type: string
          pattern: ^$|^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$
      - name: endDate
        in: query
        description: |
          Filter messages created on or before this date, as an ISO 8601 date
          or date-time. The validator accepts any string JavaScript `Date` can
          parse (so also forms like `May 1 2020` or `2999/01/01`); one it
          cannot parse returns HTTP 400. An empty value is read as not sent.
        schema:
          type: string
          pattern: ^$|^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$
      - name: messageType
        in: query
        description: Filter messages by type. An empty value is read as not sent.
        schema:
          type: string
          enum:
          - ''
          - user_query
          - bot_response
          - error
          - feedback
          - system
      responses:
        '200':
          description: Agent conversation detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConversationDetailResponse'
        '400':
          description: |
            Bad request — the request failed validation

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The access token lacks the `agent:read` OAuth scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Conversation not found: it does not exist, is deleted, belongs to
            another agent, or the caller can neither own nor see it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /agents/{agentKey}/conversations:
    get:
      tags:
      - Agents
      summary: List agent conversations
      description: |
        Paginated list of conversations for the agent (owned and shared-with-me),
        excluding archived threads.
      operationId: listAgentConversations
      security:
      - bearerAuth: []
      - oauth2:
        - agent:read
      parameters:
      - name: agentKey
        in: path
        required: true
        description: Agent identifier used to scope the conversation list.
        schema:
          type: string
      - name: page
        in: query
        description: 1-based page number. Defaults to `1`.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Page size. Defaults to `20`; maximum `100`.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: sortBy
        in: query
        description: |
          Preferred sort field. Supported values are `createdAt`,
          `lastActivityAt`, and `title`.

          The current gateway validator preserves legacy behavior: unsupported
          values are accepted but ignored, and the handler falls back to
          `lastActivityAt`.
        schema:
          type: string
      - name: sortOrder
        in: query
        description: |
          Preferred sort direction. Supported values are `asc` and `desc`.

          The current gateway validator preserves legacy behavior: unsupported
          values are accepted but ignored, and the handler falls back to
          descending order.
        schema:
          type: string
      - name: search
        in: query
        description: |
          Case-insensitive search term applied to conversation `title` and
          `messages.content`. Maximum length is 1000 characters. A printf-style
          format specifier (`%s`, `%x`, ...) is refused with `VALIDATION_ERROR`;
          markup (HTML tags, `javascript:`, event handlers) is refused with
          `HTTP_BAD_REQUEST` by the sanitizer every route runs.
        schema:
          type: string
          maxLength: 1000
          pattern: ^(?![\s\S]*?(?:(?<!\w)%(?:\d{1,10}\$)?[#0\-+ ]{0,10}(?:\d{1,10})?(?:\.\d{1,10})?(?:h{1,2}|l{1,2}|L|z|j|t)?[nsxXp]|<[^>]{0,10000}>))
      - name: startDate
        in: query
        description: |
          Inclusive lower bound on `createdAt`, as an ISO 8601 date or
          date-time. The validator accepts any string JavaScript `Date` can
          parse (so also forms like `May 1 2026`); one it cannot parse returns
          HTTP 400.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$
          example: '2026-05-26T00:00:00.000Z'
      - name: endDate
        in: query
        description: |
          Inclusive upper bound on `createdAt`, as an ISO 8601 date or
          date-time. The validator accepts any string JavaScript `Date` can
          parse (so also forms like `May 1 2026`); one it cannot parse returns
          HTTP 400.
        schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$
          example: '2026-05-27T00:00:00.000Z'
      - name: status
        in: query
        description: |
          Optional status filter applied to the `sharedWithMeConversations`
          branch of the response. The main `conversations` list ignores this
          parameter.
        schema:
          type: string
      - name: isArchived
        in: query
        description: |
          Optional archived flag applied to the `sharedWithMeConversations`
          branch before the route-level non-archived guard is enforced.
          Accepted values are `true` and `false`.
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: projectId
        in: query
        required: false
        description: |
          Restrict results to a single project. Pass a project's `id`, or
          the literal string `unassigned` to list agent conversations with
          no `projectId`. Anything else is refused with HTTP 400.
        schema:
          type: string
          pattern: ^(unassigned|[0-9a-fA-F]{24})$
      responses:
        '200':
          description: Conversation list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentConversationListResponse'
        '400':
          description: |
            Invalid path or query parameter.

            This includes Zod validation failures such as invalid pagination,
            invalid booleans, malformed date values, duplicate `search`
            parameters, or overlong / invalid `search` input.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The access token lacks the `agent:read` OAuth scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - Agents
      summary: Create agent conversation (non-streaming)
      description: |
        Start a conversation with an agent and wait for the complete answer.
        The JSON counterpart of `POST /agents/{agentKey}/conversations/stream`.

        **How a turn runs**

        1. The user's message is saved (in its own short transaction on a
           replica set).
        2. The AI backend runs the same agent-loop pipeline as the `/stream`
           route and returns only its final result. No transaction is held
           during this call, and the call is never retried.
        3. The answer, citations and status are saved exactly as the
           streaming route saves them, and the updated conversation is
           returned.

        Every failure after step 1 is persisted: the conversation ends with
        status `Failed`, a `failReason`, and an `error` message, and the
        response carries `X-Conversation-Id` so the caller can fetch it.
        A 4xx from the AI backend (for example no model configured) keeps
        its status and user-facing message; other failures return 500 with
        a generic message.

        The response arrives only when the whole answer is ready, which can
        take minutes for agent runs. Allow a generous client and proxy
        timeout, or use the `/stream` variant for interactive clients.
      operationId: createAgentConversation
      security:
      - bearerAuth: []
      - oauth2:
        - agent:execute
      parameters:
      - name: agentKey
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: |
          The first question, with optional scope, model, project and tool overrides. A `query`
          that holds markup or a printf-style format specifier is refused with `400`
          `HTTP_BAD_REQUEST`, and so is one of only whitespace ("Query is required").
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreateConversationRequest'
      responses:
        '201':
          description: Conversation created with the agent's first answer.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAgentConversationResponse'
        '400':
          description: |
            Invalid request. Field validation failures answer `VALIDATION_ERROR`
            (`query` missing, empty or over 100,000 characters, a malformed id,
            an unknown enum value, an incomplete `appliedFilters` node, ...).
            A `query` holding a printf-style format specifier (`%s`, `%x`, ...)
            and any string field holding markup (HTML tags, `javascript:`, event
            handlers) answer `HTTP_BAD_REQUEST` before a conversation is saved;
            this route checks markup itself, after authentication, because the
            app-wide filter skips POST and PUT under `/agents/`.

            A `previousConversations` field holding anything but an empty list (`HTTP_BAD_REQUEST`,
            `previousConversations is not accepted. Conversation history is read from the stored
            conversation: create the conversation, then send follow-up questions to its messages
            endpoint.`). Checked after authentication and before the body validator; an empty list is
            dropped.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — valid bearer token required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — the token lacks the `agent:execute` OAuth scope, or, with a `projectId`, lacks `project:read`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            `projectId` names no project the caller can see (refused before a
            conversation is saved), or the AI backend has no agent with this key
            or the caller has no access to it (an agent not shared with a
            member is not a 403):
            that turn fails after the user message is saved, the conversation is
            kept with status `Failed`, and `X-Conversation-Id` names it.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The `projectId` names an archived project (`HTTP_CONFLICT`); unarchive it to start chats in it. Refused before a conversation is saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: The request is larger than the selected model accepts.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '422':
          description: The model provider's content filter blocked the request.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '424':
          description: |
            No usable LLM — none is configured for the organization, the
            selected one could not start, or its provider rejected the API
            key or could not find the model. The message says what to fix.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: The model provider is rate limiting or out of quota.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
        '500':
          description: |
            The answer failed (the AI service returned no answer, or it could
            not be saved). The conversation is kept with
            status `Failed` and an `error` message.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: |
            The AI service could not be reached (for example, it is still
            starting). The conversation is marked `Failed`; that save is best
            effort, so if it fails the conversation keeps its previous status.
            Sending the message again may repeat work the AI service had started.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: |
            The AI service did not answer in time. The conversation is marked
            `Failed`; that save is best effort, so if it fails the conversation
            keeps its previous status. The AI service may have started the turn,
            so sending the message again may repeat work it had started.
          headers:
            X-Conversation-Id:
              $ref: '#/components/headers/X-Conversation-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/registry:
    get:
      tags:
      - Connector Registry
      summary: List available connector types
      description: |
        Get all available connector types from the registry.<br><br>
        <b>Overview:</b><br>
        The registry contains all connector types that can be configured as instances.
        Each type has specific authentication requirements, supported scopes, and capabilities.<br><br>
        <b>Connector Types Include:</b><br>
        <ul>
        <li><b>Google Workspace:</b> Drive, Gmail, Calendar, etc.</li>
        <li><b>Microsoft 365:</b> OneDrive, Outlook, SharePoint, etc.</li>
        <li><b>Cloud Storage:</b> Dropbox, Box, AWS S3</li>
        <li><b>Collaboration:</b> Slack, Confluence, Notion, Jira</li>
        <li><b>Databases:</b> PostgreSQL, MySQL, MongoDB</li>
        </ul>
        <b>Filtering:</b><br>
        Use <code>scope</code> to filter by team or personal connectors.
        Use <code>search</code> for full-text search across connector names.
      operationId: getConnectorRegistry
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: scope
        in: query
        description: Which connector types to list. Defaults to `team`.
        schema:
          title: ConnectorRegistryScope
          allOf:
          - $ref: '#/components/schemas/ConnectorScope'
          default: team
      - name: page
        in: query
        description: Page number
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Items per page
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
      - name: search
        in: query
        description: |
          Case-insensitive search across name, type, app group, description,
          auth types and categories. Every whitespace-separated word must match.
        schema:
          type: string
      - name: isAuthenticated
        in: query
        description: |
          Validated (must be <code>true</code> or <code>false</code>) but
          ignored by this endpoint: it filters nothing. The parameter exists
          because the query validator is shared with <code>GET /connectors</code>.
        schema:
          type: boolean
      - name: isActive
        in: query
        description: |
          Validated (must be <code>true</code> or <code>false</code>) but
          ignored by this endpoint: it filters nothing.
        schema:
          type: boolean
      - name: connectorType
        in: query
        description: |
          Validated (must not be empty or blank: the value is trimmed before
          it is checked) but ignored by this endpoint: it filters nothing.
        schema:
          type: string
          minLength: 1
          pattern: \S
      responses:
        '200':
          description: Connector registry retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  connectors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConnectorRegistryEntry'
                  pagination:
                    $ref: '#/components/schemas/ConnectorPagination'
                  registryCountsByScope:
                    type: object
                    description: How many connector types each scope offers
                    properties:
                      team:
                        type: integer
                      personal:
                        type: integer
                required:
                - success
                - connectors
                - pagination
        '400':
          description: |
            Invalid request: a parameter or the body failed validation

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The registry has no connector types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/registry/{connectorType}/schema:
    get:
      tags:
      - Connector Registry
      summary: Get connector configuration schema
      description: |
        The configuration form for one connector type.<br><br>
        <b>Sections:</b><br>
        <ul>
        <li><b>auth:</b> <code>supportedAuthTypes</code>, and per auth type in <code>schemas</code> the
        fields to send in <code>config.auth</code> (by <code>name</code>) plus, for OAuth, the
        <code>redirectUri</code> path</li>
        <li><b>sync:</b> <code>supportedStrategies</code>, <code>scheduledConfig</code> defaults, and the
        connector's own settings in <code>customFields</code> (sent in <code>config.sync</code> by
        <code>name</code>)</li>
        <li><b>filters:</b> the <code>sync</code> and <code>indexing</code> filter fields; a field with
        <code>optionSourceType: dynamic</code> gets its values from
        <code>GET /connectors/{connectorId}/filters/{filterKey}/options</code></li>
        </ul>
      operationId: getConnectorSchema
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: connectorType
        in: path
        required: true
        description: 'Connector type: `type` from GET /connectors/registry'
        schema:
          type: string
          pattern: ^(?!\.{1,2}$)[^/\\?#%\x00-\x1f\x7f]+$
        example: Jira
      responses:
        '200':
          description: Connector schema retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  schema:
                    $ref: '#/components/schemas/ConnectorSchema'
                required:
                - success
                - schema
        '400':
          description: |
            Invalid request: a parameter or the body failed validation

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/registry/{connectorType}/test-connection:
    post:
      tags:
      - Connector Registry
      summary: Test connector credentials before saving
      description: |
        Try the auth settings from a connector's setup form without creating or
        changing an instance.<br><br>
        <b>Overview:</b><br>
        Only connector types whose schema has <code>supportsConnectionCheck: true</code>
        can be tested. A failed check is not an error: the response is
        <code>200</code> with <code>success: false</code> and a <code>message</code>
        to show the user (for example a wrong password, an unknown database, or a
        timeout because a firewall blocks PipesHub's IP address).<br><br>
        <b>Editing an instance:</b><br>
        Pass <code>connectorId</code> to lay the settings over the instance's saved
        ones, as <code>PUT /connectors/{connectorId}/config/auth</code> does. The
        caller must be allowed to update that instance.
      operationId: testConnectorConnection
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
      parameters:
      - name: connectorType
        in: path
        required: true
        description: |
          Connector type as listed by `GET /connectors/registry` (its `type`),
          URL-encoded. The lookup is case-sensitive.
        schema:
          type: string
        example: PostgreSQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - auth
              properties:
                auth:
                  type: object
                  description: Auth values, keyed by the fields of the connector's auth schema
                  additionalProperties: true
                  example:
                    host: db.example.com
                    port: '5432'
                    database: analytics
                    username: reader
                    password: your-password
                connectorId:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{1,64}$
                  description: |
                    Instance being edited; its saved auth values fill in fields left out.
                    A secret sent as `••••••••` (the mask the config routes return) keeps the
                    stored value; any other value that is sent replaces the saved one.
      responses:
        '200':
          description: Check ran; see <code>success</code>
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - success
                - message
                properties:
                  success:
                    type: boolean
                    description: Whether the connector reached the source with these settings
                  message:
                    type: string
                    description: What happened, written for the user
              example:
                success: false
                message: PostgreSQL rejected the login for user "reader". Check the username and password.
        '400':
          description: |
            Refused. Possible reasons:<br>
            <ul>
            <li><code>VALIDATION_ERROR</code> - the body is not a JSON object; <code>auth</code> is missing, <code>null</code> or not an object; or <code>connectorId</code> is not a string of 1-64 letters, digits, underscores or hyphens</li>
            <li>The connector type has no connection check (<code>&lt;type&gt; has no connection check</code>)</li>
            <li><code>connectorId</code> names an instance of another connector type</li>
            <li><code>connectorType</code> is not a safe path segment (for example it contains an encoded <code>/</code>); answered before the token is checked</li>
            </ul>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            The OAuth token lacks the `connector:write` scope.
            Also returned for a beta connector type (Calendar, Meet, Forms, Slides,
            Docs, Zendesk, Airtable) while the platform feature flag
            `ENABLE_BETA_CONNECTORS` is off (the default), with the message
            `Beta connectors are not enabled. The connector '<type>' is a beta connector and cannot be accessed. ...`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Connector type not found in the registry, or `connectorId` matches no
            instance the caller can see (another user's personal connector, or
            another user's team connector for a member).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error, for example when the JSON body is not an object

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable - Connector service is unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/network/egress-ips:
    get:
      tags:
      - Connector Registry
      summary: Get the IP addresses connectors connect from
      description: |
        Public IP addresses PipesHub's connectors use to reach external systems, for
        users to allow in a database's or API's firewall.<br><br>
        Set by the deployment through <code>CONNECTOR_EGRESS_IPS</code>; otherwise
        looked up by the connector service and cached. The list is empty when the
        address cannot be determined, or when the deployment sets
        <code>CONNECTOR_EGRESS_IPS=none</code>.
      operationId: getConnectorEgressIps
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      responses:
        '200':
          description: Egress IP addresses
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                - success
                - egressIps
                properties:
                  success:
                    type: boolean
                  egressIps:
                    type: array
                    items:
                      type: string
                    example:
                    - 203.0.113.10
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service unavailable - Connector service is unreachable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: |
            Returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors:
    get:
      tags:
      - Connector Instances
      summary: List connector instances
      description: |
        Get all configured connector instances for your organization.<br><br>
        <b>Overview:</b><br>
        Returns instances created by users, filtered by scope and permissions.
        Team-scope connectors are visible to all org users. Personal connectors
        are only visible to their creators, not even to admins. Knowledge bases
        (instances of type <code>KB</code>) are not listed here.<br><br>
        <b>Instance States:</b><br>
        <ul>
        <li><b>isConfigured:</b> All required settings are complete</li>
        <li><b>isAuthenticated:</b> OAuth flow complete or credentials valid</li>
        <li><b>isActive:</b> Connector is enabled for sync/agent</li>
        <li><b>desktopOnline:</b> Owner device's desktop app connected (Local FS only)</li>
        <li><b>ownerDeviceId / ownerDeviceName:</b> Desktop device that owns the connector, set on first enable (Local FS only)</li>
        </ul>
      operationId: listConnectorInstances
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: scope
        in: query
        required: false
        description: |
          Filter by scope. Defaults to <code>team</code> when omitted.
        schema:
          title: ConnectorInstanceListScope
          allOf:
          - $ref: '#/components/schemas/ConnectorScope'
          default: team
      - name: page
        in: query
        description: Page number, 1-based
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: Items per page
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
      - name: search
        in: query
        description: |
          Full-text search across instance name, type, and app group. The term
          is not echoed back in <code>pagination</code>.
        schema:
          type: string
      - name: isAuthenticated
        in: query
        description: |
          Filter by authentication status.
          <code>true</code> returns only authenticated instances;
          <code>false</code> returns only unauthenticated ones.
          Omit to return all.
        schema:
          type: boolean
      - name: isActive
        in: query
        description: |
          Filter by active status.
          <code>true</code> returns only active instances;
          <code>false</code> returns only inactive ones.
          Omit to return all.
        schema:
          type: boolean
      - name: connectorType
        in: query
        description: |
          Filter by exact connector type string (e.g. <code>Confluence</code>,
          <code>GoogleDrive</code>). Case-sensitive. An empty or blank value
          is refused with `400` (the value is trimmed before it is checked).
        schema:
          type: string
          minLength: 1
          pattern: \S
      responses:
        '200':
          description: Instances retrieved
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - connectors
                - pagination
                properties:
                  success:
                    type: boolean
                  connectors:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConnectorInstance'
                  pagination:
                    $ref: '#/components/schemas/ConnectorPagination'
        '400':
          description: |
            A query parameter failed validation, for example an unknown `scope`, a
            non-boolean `isActive` or a `limit` above 200

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - Connector Instances
      summary: Create connector instance
      description: |
        Create a connector instance from a registry type.<br><br>
        <b>Body:</b><br>
        Put the auth fields the registry schema lists for <code>authType</code> in <code>config.auth</code>,
        flat, and the connector's own sync settings in <code>config.sync</code>. A connector that needs no
        OAuth sign-in is configured on creation.<br><br>
        <b>OAuth:</b><br>
        An admin may send the OAuth app's credentials in <code>config.auth</code>: the app is saved and
        linked. Anyone may send <code>config.auth.oauthConfigId</code> to use a saved app; non-admins must.
        Send <code>baseUrl</code>: the provider redirects to <code>{baseUrl}/{redirectUri}</code>.<br><br>
        <b>Scope Permissions:</b><br>
        <ul>
        <li><code>team</code> scope requires admin privileges</li>
        <li><code>personal</code> scope available to all users</li>
        </ul>
        <b>Next Steps After Creation:</b><br>
        <ol>
        <li>OAuth only: <code>GET /{id}/oauth/authorize</code>, then <code>GET /oauth/callback</code></li>
        <li>Optionally set sync and filters via <code>PUT /{id}/config/filters-sync</code></li>
        <li>Turn sync on via <code>POST /{id}/toggle</code></li>
        </ol>
      operationId: createConnectorInstance
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectorRequest'
            examples:
              rss:
                summary: RSS (no sign-in)
                value:
                  connectorType: RSS
                  instanceName: Company blog
                  scope: team
                  config:
                    sync:
                      feed_urls: https://example.com/feed.xml
                      max_articles_per_feed: 50
              postgresBasicAuth:
                summary: PostgreSQL with a username and password
                value:
                  connectorType: PostgreSQL
                  instanceName: Analytics database
                  scope: team
                  authType: BASIC_AUTH
                  config:
                    auth:
                      host: db.example.com
                      port: 5432
                      database: analytics
                      username: reader
                      password: your-password
              jiraNewOAuthApp:
                summary: Jira, admin saving a new OAuth app
                value:
                  connectorType: Jira
                  instanceName: Engineering Jira
                  scope: team
                  authType: OAUTH
                  baseUrl: https://pipeshub.example.com
                  config:
                    auth:
                      clientId: your-atlassian-client-id
                      clientSecret: your-atlassian-client-secret
                      oauthInstanceName: Atlassian app
              jiraSavedOAuthApp:
                summary: Jira with a saved OAuth app (team scope needs an admin; non-admins use this form with scope personal)
                value:
                  connectorType: Jira
                  instanceName: Engineering Jira
                  scope: team
                  authType: OAUTH
                  baseUrl: https://pipeshub.example.com
                  config:
                    auth:
                      oauthConfigId: 3fa85f64-5717-4562-b3fc-2c963f66afa6
              oneDrive:
                summary: OneDrive (Team)
                value:
                  connectorType: OneDrive
                  instanceName: Company OneDrive
                  scope: team
                  authType: OAUTH_ADMIN_CONSENT
              jiraPersonal:
                summary: Jira Cloud (Personal, API token)
                value:
                  connectorType: Jira Cloud Personal
                  instanceName: My Jira
                  scope: personal
                  authType: API_TOKEN
      responses:
        '200':
          description: Connector instance created. It is not syncing yet.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  connector:
                    $ref: '#/components/schemas/ConnectorCreated'
                  message:
                    type: string
                    example: Connector instance created successfully.
                required:
                - success
                - connector
        '400':
          description: |
            Invalid request: a parameter or the body failed validation, or `config.auth` is present
            but neither an object nor null ("Auth configuration must be an object.")
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Team scope needs an admin; non-admins cannot send OAuth app credentials; or a missing scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown connector type or OAuth app
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: An OAuth app with that name already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error, for example when the JSON body is not an object

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}:
    get:
      tags:
      - Connector Instances
      summary: Get connector instance
      description: |
        Retrieve a specific connector instance by ID, together with the setup
        form of its connector type (<code>config</code>).<br><br>
        <b>Who can read an instance:</b><br>
        <ul>
        <li>Team scope: the creator and org admins. Other members get
        <code>404</code>, although the lists show them the instance.</li>
        <li>Personal scope: the creator only. An admin gets <code>404</code>.</li>
        </ul>
        The ID of a knowledge base is accepted too: a knowledge base is stored
        as a connector instance of type <code>KB</code>.
      operationId: getConnectorInstance
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: connectorId
        in: path
        required: true
        description: Connector instance ID (`_key` of the instance)
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
      responses:
        '200':
          description: Connector instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  connector:
                    $ref: '#/components/schemas/ConnectorInstance'
                required:
                - success
                - connector
        '400':
          description: |
            Invalid request: `connectorId` is not 1 to 64 letters, digits, underscores or hyphens
            (`VALIDATION_ERROR`, "Connector ID must be 1-64 chars of letters, digits, underscore, or hyphen").

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - Connector Instances
      summary: Delete connector instance
      description: |
        Start the deletion of a connector instance and all associated data.<br><br>
        <b>Asynchronous:</b><br>
        The request is answered with <code>202</code> as soon as the instance is
        marked <code>DELETING</code>; its sync is stopped and its records,
        vectors and configuration are removed in the background.<br><br>
        <b>Permissions:</b><br>
        <ul>
        <li>The creator can delete their own instance</li>
        <li>An org admin can delete any instance, including another user's
        personal one (which the admin cannot read)</li>
        <li>Anyone else gets <code>404</code></li>
        </ul>
        <b>In use:</b><br>
        Refused with <code>409</code> while an agent uses the instance as a
        knowledge source.
      operationId: deleteConnectorInstance
      security:
      - bearerAuth: []
      - oauth2:
        - connector:delete
      parameters:
      - name: connectorId
        in: path
        required: true
        description: Connector instance ID (`_key` of the instance)
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
      responses:
        '202':
          description: |
            Deletion accepted. The connector is marked `DELETING` and removed in
            the background, so a `GET` shortly afterwards answers `404`.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - message
                - connectorId
                - status
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: Connector deletion initiated
                  connectorId:
                    type: string
                    description: ID of the connector being deleted
                  status:
                    type: string
                    enum:
                    - DELETING
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            The OAuth client's token lacks the `connector:delete` scope.
            Also returned for an instance of a beta connector type (Calendar, Meet,
            Forms, Slides, Docs, Zendesk, Airtable) while the platform feature flag
            `ENABLE_BETA_CONNECTORS` is off (the default), with the message
            `Beta connectors are not enabled. The connector '<type>' is a beta connector and cannot be accessed. ...`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            The connector doesn't exist (or was already deleted), or the caller is
            neither its creator nor an admin. The two answers are the same, so the
            route doesn't reveal connectors the caller can't delete.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            The connector cannot be deleted now: an agent uses it as a knowledge source
            (the message names the agents), its deletion is already in progress, or
            another operation such as a sync holds it locked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: |
            `connectorId` is not 1-64 characters of letters, digits, `_` or `-`
            (`VALIDATION_ERROR`), or is not a safe path segment (for example it contains an
            encoded `/`; `HTTP_BAD_REQUEST`, answered before the token is checked).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}/stats:
    get:
      tags:
      - Connector Instances
      summary: Get connector statistics
      description: |
        Retrieve record counts of a connector instance, in total and per record
        type, broken down by indexing status. The ID of a knowledge base is
        accepted too (a knowledge base is stored as a connector instance of type
        <code>KB</code>); its stats report <code>origin: COLLECTION</code>.<br><br>
        <b>Who can read them:</b> the creator of the instance and, for a team
        instance, org admins. Stats use the same read gate as
        <code>GET /connectors/{connectorId}</code>: anyone else, including an
        admin reading another user's personal instance, gets <code>404</code>
        ("This connector was removed, or you no longer have access. ..."), so
        the instance's existence is not confirmed.

        An OAuth token holding `kb:read` instead of `connector:read` passes the scope check too.
      operationId: getConnectorStats
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: connectorId
        in: path
        required: true
        description: |
          Connector instance ID (`_key` of the instance) or knowledge base ID.
          Unlike the other instance routes, the ID is not checked against a
          pattern: an ID no instance has is answered `404`.
        schema:
          type: string
      responses:
        '200':
          description: Connector statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorStats'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            The OAuth client's token lacks the `connector:read` or `kb:read`
            scope, or the ID is a knowledge base on which the caller has a role
            other than OWNER, WRITER or READER.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            No connector instance or knowledge base has this ID, or the caller
            cannot open it (not the creator, and not an admin of a team
            instance; another user's personal instance is not found for admins
            either; a knowledge base the caller has no role on).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: |
            `connectorId` is not a safe path segment (for example it contains an
            encoded `/`). Answered before the token is checked.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/record/{recordId}/content:
    get:
      tags:
      - Connector
      summary: Get a record's full parsed content and metadata
      description: |
        Retrieve the full parsed content and metadata of a single record —
        the same content PipesHub's own RAG/chat pipeline uses to answer
        questions, returned directly instead of via chat.

        **When to use this vs. the other record endpoints:**
        - `GET /knowledgeBase/record/{recordId}` returns metadata only
          (name, type, indexing status, size) — no content.
        - `GET /knowledgeBase/stream/record/{recordId}` returns the original,
          unparsed file bytes — use it to download/open the source file.
        - **This endpoint** returns the record's full parsed content as a
          single plain-text `content` string (a metadata header, then the
          block/table text in reading order, then any foreign-key related
          tables) — use it when you need the record's actual textual/tabular
          content without downloading and re-parsing the original file yourself.

        **Typical flow:** obtain a `recordId` from a `pipeshub_search` hit or
        a chat citation's `recordId`, then call this endpoint to read the
        full content when the search snippet or citation excerpt isn't
        enough to answer the question.

        **Reading part of a long record, or a whole Slack thread:**

        With no query parameters the record is returned up to 140,000
        characters (a longer one is cut and marked `truncated`), which for a
        pull request with its diffs or a long document is a large response. Pass any of `maxChars`, `startBlock`, `query`
        or `mode` for a budgeted read instead: the response stays within
        `maxChars` and says how to continue (`nextStartBlock`, or
        `nextStartRecord` for a thread). `query` makes a record too large for
        the budget show its most relevant blocks first, with the skipped
        ranges marked. `mode=thread` returns every message of the Slack
        thread the record belongs to, oldest first, as far as the caller may
        see them. A Slack record in no single thread (several channel
        messages in one record, or a message without replies) returns itself,
        then the replies of each thread its messages started; the first page
        opens with a bracketed note saying which.

        **Permission scoping:**

        The requesting user/token must have access to the record; access is
        verified via the knowledge graph before content is returned — a
        caller with a valid scope but no access to this specific record gets
        a `403`.

        **A connected app with a limit:** the rendered text names nothing
        outside the limit beside the record. Its `External Parent ID` reads
        `N/A` for a parent the limit leaves out, and a code file's `Path:`
        line is left out unless the limit covers the whole app. Linked
        records, related tables, a deal's orgs and products, and live Jira
        parent, epic, sub-task and linked-issue lines appear only for
        records inside the limit. `Web URL` is kept, though it can contain
        folder names.
      operationId: getRecordContent
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: recordId
        in: path
        required: true
        description: Record ID to fetch. Obtain it from a `pipeshub_search` result (`hits[*].recordId`) or a chat citation (`citations[*].recordId`).
        schema:
          type: string
      - name: maxChars
        in: query
        required: false
        description: Most characters of `content` to return. Asks for a budgeted read; 40000 when another budgeted-read parameter is given without it.
        schema:
          type: integer
          minimum: 2000
          maximum: 140000
      - name: extract
        in: query
        required: false
        description: 'With `query`, in record mode and without `startBlock`: return only the passages that answer `query`, as the model assigned to the `reader` role (else the default model) copies them out, instead of the record''s text. The model is told to copy word for word, and `extract.unverifiedLines` counts the lines it did not. The response''s `order` is `extract`, and its `extract` object names the model and the tokens it used. When the model cannot be reached, the usual read is returned with `extract.error` set.'
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
      - name: startBlock
        in: query
        required: false
        description: 'Read in order from this block: the `nextStartBlock` of a previous read, or 0 for the top. Takes precedence over `query`. In thread mode it applies to the record at `startRecord`; later records are read from their start.'
        schema:
          type: integer
          minimum: 0
      - name: query
        in: query
        required: false
        description: What you are looking for in the record. When the record does not fit in `maxChars`, the blocks most relevant to it are shown first and the skipped ranges are marked.
        schema:
          type: string
          minLength: 1
          maxLength: 2000
      - name: mode
        in: query
        required: false
        description: '`record` (default) reads this record. `thread` reads every record of the Slack thread this message belongs to, oldest first. A Slack record in no single thread reads as itself, then the threads its messages started (at most 10). A record that is not from Slack answers `422`.'
        schema:
          type: string
          enum:
          - record
          - thread
      - name: startRecord
        in: query
        required: false
        description: 'Thread mode: start at this record of the thread, the `nextStartRecord` of a previous read. Pass the read''s `nextStartBlock` with it.'
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: |
            Successful operation. When the record exists but its content is
            not indexed yet, `content` describes the record (name, link,
            dates) and ends with a `Not indexed:` paragraph naming its
            indexing status. When the record is indexed but its stored
            content could not be loaded, `content` is the literal
            `No record found`. Neither is an error status. An id that does
            not exist, or a record the caller may not read, answers `403`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRecordContentResponseSchema'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            OAuth token is missing the `connector:read` scope, or the
            authenticated user does not have access to this record. A record
            ID that does not exist is answered the same way, so the route
            never reveals whether a record exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            The record belongs to demo data the caller has switched off
            (`Record not found`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: |
            `mode=thread` was asked of a record that is not from Slack. Every
            Slack message record can be read in thread mode. Also returned for
            `extract=true` without a `query`, with `startBlock`, or with
            `mode=thread`: an extract reads one record for a question.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while fetching record content.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: |
            `recordId` is not a safe path segment (for example it contains an
            encoded `/`). Answered before the token is checked. Also `VALIDATION_ERROR`
            when `mode`, `query`, `startBlock`, `startRecord` or `maxChars` is outside
            its documented values or range.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/navigate:
    get:
      tags:
      - Connector
      summary: Browse the knowledge graph from a node
      description: |
        Open a node in the knowledge graph and see what is inside it — a file
        explorer across every connected source.

        Call it with no `nodeId` for a flat listing of every record group and
        record the caller can reach, newest first. This is a starting point to
        pick a node from, not a roster of connected apps — app nodes are not
        returned in a listing (except at the root of a limited connected app,
        below), though an app's `id` is accepted as a `nodeId` and lists that
        app's record groups. Pass a node's `id` to descend:
        record groups contain records and folders, and a record contains its
        own children — comments, attachments, sub-tasks — plus a `related`
        section of cross-referenced records, such as the Confluence page linked
        from a Jira ticket. `nodeId` is tolerant: a URL or an issue key such as
        `PA-1787` is resolved to its record before navigating, so a link can be
        pasted straight in without a separate lookup call.

        The response carries a rendered `text` view — breadcrumbs, the current
        node, the children listing, `Related:`, and a closing `Next:` line
        naming a follow-up call. The structured fields carry the same
        information for programmatic use.

        **When to use this vs. the other record endpoints:**
        - **This endpoint** is for structural exploration — "what is in this
          project", "what is attached to this ticket", "what else links to this
          page". It returns names, types and IDs; it never returns document
          text.
        - `GET /connectors/record/{recordId}/content` returns one record's
          actual parsed text. Use it once navigation has identified the record
          you want to read.
        - `GET /connectors/record/lookup` is the way in when you hold a URL or
          an issue key rather than a position in the tree.

        **Typical flow:** call with no `nodeId` to see what is reachable → pass
        a record group's `id` to list its records → take a row whose
        `is_record` is true and call
        `GET /connectors/record/{recordId}/content` to read it.

        **Paging and depth:** results are paginated; `pagination.has_next`
        tells you whether to request the next `page`. `depth` above 1 returns
        all descendants down to that level as one flat list, each row carrying
        its own `level`, instead of only direct children.

        **Scope:** everything the caller can read, across both connectors and
        Knowledge Base collections. No connector-level filter is applied — the
        listing is bounded by per-node permissions, and for a connected app
        with a limit by that limit too: no row, breadcrumb or related node
        outside it is returned.

        **A connected app with a limit:** with no `nodeId`, the root depends
        on what the limit names.
        - Whole sources (apps or collections) only: the usual flat root,
          every record group and record in those sources.
        - Any spaces, folders or files, alone or beside whole sources: one
          row for each whole source, space (record group), folder and file
          the limit names, and nothing from inside them. `pagination.total`
          counts those rows, not the records inside them. `depth` is not
          applied on this call; pass a row's `id` as `nodeId` to open it.

        **Permission scoping:**

        `rows` and `related` carry only nodes the caller can see, and the
        opened node itself is access-checked before any of its details are
        returned. A node that does not exist and a node the caller cannot
        access are deliberately indistinguishable — both return an empty view
        rather than an error.

        `breadcrumbs` is the exception: the ancestor trail is resolved by id
        alone, without a permission check. For a record shared directly with
        the caller, it can therefore name ancestors the caller cannot open.
        Treat breadcrumb entries as labels, not as nodes guaranteed to be
        navigable.

        **A connected app with a limit:** the opened record's `context_block`, and each row's
        `context_summary`, names nothing
        outside the limit beside the record. Its `External Parent ID` reads
        `N/A` for a parent the limit leaves out, and a code file's `Path:`
        line is left out unless the limit covers the whole app. Linked
        records, related tables, a deal's orgs and products, and live Jira
        parent, epic, sub-task and linked-issue lines appear only for
        records inside the limit. `Web URL` is kept, though it can contain
        folder names.

        **Connector and knowledge base nodes:** opening the `id` of a
        connector instance the caller has no permission on in the graph (for
        example one that has never synced, even for its creator) returns the
        same empty view as a missing node. Opening a knowledge base at
        `depth` 1 lists nothing; its records appear from `depth` 2.

        An OAuth token holding `connector:read` instead of `kb:read` is accepted too.
      operationId: navigateKnowledgeGraph
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      parameters:
      - name: nodeId
        in: query
        required: false
        description: 'The node to open. Take it from an `id` in a previous navigate or lookup response. Omit it entirely for the flat listing of everything reachable — the usual starting point. A URL or an issue key such as `PA-1787` also works: it is resolved to its record automatically. The value is trimmed before it is checked, so a blank one is refused like an empty one.'
        schema:
          type: string
          minLength: 1
          maxLength: 2048
          pattern: \S
      - name: page
        in: query
        required: false
        description: Page number, 1-indexed.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        required: false
        description: Children per page. The minimum is 50 — smaller values are rejected rather than silently raised.
        schema:
          type: integer
          minimum: 50
          maximum: 200
          default: 50
      - name: depth
        in: query
        required: false
        description: Levels of descendants to return in one call. Above 1, `rows` is a flat list of all descendants down to that level rather than only direct children, and each row carries its own `level`.
        schema:
          type: integer
          minimum: 1
          maximum: 3
          default: 1
      - name: nodeTypes
        in: query
        required: false
        description: 'Restrict children to these node types. Repeat the parameter for multiple types: `?nodeTypes=record&nodeTypes=folder`. A single value is read as a list of one. The types that filter are `app`, `recordGroup`, `record` and `folder`; any other value is accepted and ignored, so it does not narrow the listing.'
        schema:
          type: array
          items:
            type: string
      - name: createdAfter
        in: query
        required: false
        description: Filter children by source creation time. ISO 8601 `YYYY-MM-DD`, or a full datetime that MUST carry a timezone offset — a naive datetime is rejected rather than assumed to be UTC. Must not be in the future (5 minutes of clock skew are tolerated) and must not be after `createdBefore`. A `YYYY-MM-DD` day past the end of its month (`2024-02-31`) counts from the first day of the next month here, and as the month's last day in a `...Before` bound. A day above 31, a month above 12 or year 0 (`2024-02-32`) is refused with `400`.
        schema:
          $ref: '#/components/schemas/NavigateDateQuery'
      - name: createdBefore
        in: query
        required: false
        description: Filter children by source creation time. `YYYY-MM-DD` is inclusive of the whole day.
        schema:
          $ref: '#/components/schemas/NavigateDateQuery'
      - name: modifiedAfter
        in: query
        required: false
        description: Filter children by source modification time. Must not be after `modifiedBefore`.
        schema:
          $ref: '#/components/schemas/NavigateDateQuery'
      - name: modifiedBefore
        in: query
        required: false
        description: Filter children by source modification time. `YYYY-MM-DD` is inclusive of the whole day.
        schema:
          $ref: '#/components/schemas/NavigateDateQuery'
      responses:
        '200':
          description: |
            Successful operation. A node that does not exist or is not
            accessible returns an empty view (null `current`, empty `rows`)
            rather than an error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavigateKnowledgeGraphResponseSchema'
        '400':
          description: |
            A parameter failed validation. Refused by the gateway
            (`VALIDATION_ERROR`): `page` below 1, `limit` outside 50-200,
            `depth` outside 1-3, an empty or blank `nodeId` or date, a parameter
            other than `nodeTypes` sent more than once. Refused by the connector
            service (`HTTP_BAD_REQUEST`): a date that is not ISO 8601, carries no
            timezone offset, is not a calendar date, forms an inverted range, or
            has `createdAfter` in the future.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: OAuth token is missing both the `kb:read` and `connector:read` scopes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The authenticated user could not be resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while navigating the knowledge graph.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/record/lookup:
    get:
      tags:
      - Connector
      summary: Resolve a URL, issue key or external ID to a Record ID
      description: |
        Turn an external reference into the matching PipesHub record. Accepts a
        pasted link, a Jira-style issue key, or a bare external system ID from
        any connected source. Repeat `identifiers` to batch-resolve up to ten
        in one call.

        The response carries a rendered `text` view — each match's metadata
        block followed by a `Next:` line naming a follow-up call. The structured
        fields carry the same information for programmatic use.

        **Accepted identifiers**
        - Jira issue URL — `https://acme.atlassian.net/browse/PA-1787`
        - Jira issue key — `PA-1787`
        - Confluence page URL —
          `https://acme.atlassian.net/wiki/spaces/SD/pages/450625553/Agent+Loop`
        - Google Drive / Docs URL — `https://docs.google.com/document/d/1AbC.../edit`
        - Slack message link — `https://acme.slack.com/archives/C0123/p1720000000000100`
        - Bare external system ID — `450625553`

        **When to use this vs. the other record endpoints:**
        - **This endpoint** converts an *external* reference into an internal
          Record ID. Reach for it whenever you meet a link or ticket key and
          need the record behind it.
        - `GET /connectors/record/{recordId}/content` reads a record you have
          already identified. It needs an internal Record ID, which is exactly
          what this endpoint returns.
        - `GET /connectors/navigate` browses the hierarchy when you have a
          position in the tree rather than a specific identifier.

        **Typical flow:** call this with the reference, take a match's `id`
        from the response, then call
        `GET /connectors/record/{recordId}/content` to read the record.

        **Multiple matches:** one identifier can legitimately match more than
        one record — the same external ID may exist in several connected
        instances. In that case the response sets `ambiguous: true` and
        `matches` holds every candidate. Present the choice rather than taking
        the first; `connectorName` narrows a retry.

        **Misses are not errors.**

        Only records the caller can see are returned, and a miss is a `200`
        with an empty `matches` array and the input echoed in
        `not_found_identifiers` — not a `404`. The identifier resolved to
        nothing *or* to something the caller may not access; the two are
        deliberately indistinguishable, because an identifier is
        caller-supplied and guessable, and confirming existence would leak
        records across organizations. `searched_connectors` names what was
        covered, so a retry with `connectorName` is often the right next move.

        **Scope:** resolution searches every connector the caller can access,
        regardless of any source filter used elsewhere.

        **A connected app with a limit:** each match's `context_block` names nothing
        outside the limit beside the record. Its `External Parent ID` reads
        `N/A` for a parent the limit leaves out, and a code file's `Path:`
        line is left out unless the limit covers the whole app. Linked
        records, related tables, a deal's orgs and products, and live Jira
        parent, epic, sub-task and linked-issue lines appear only for
        records inside the limit. `Web URL` is kept, though it can contain
        folder names.

        An OAuth token holding `connector:read` instead of `kb:read` is accepted too.
      operationId: lookupRecordByIdentifier
      security:
      - bearerAuth: []
      - oauth2:
        - kb:read
      parameters:
      - name: identifiers
        in: query
        required: true
        description: 'The reference(s) to resolve: a URL, an issue key such as `PA-1787`, or a bare external system ID. Repeat the parameter to batch: `?identifiers=PA-1787&identifiers=PA-1788`. Maximum 10.'
        schema:
          type: array
          minItems: 1
          maxItems: 10
          items:
            type: string
            minLength: 1
            maxLength: 2048
            pattern: \S
      - name: connectorName
        in: query
        required: false
        description: Optional hint that prioritises resolution order, e.g. `JIRA`, `CONFLUENCE`, `DRIVE`, `SLACK` (the `ConnectorNameEnum` values). Any other non-empty string is accepted too and simply matches no connector, so it changes nothing. It cannot widen the search beyond the connectors the caller can already access. Useful on a retry when a lookup came back empty. An empty or blank value is refused with `400` (the value is trimmed before it is checked).
        schema:
          type: string
          minLength: 1
          pattern: \S
      responses:
        '200':
          description: |
            Successful operation. Identifiers that resolved to nothing the
            caller can access are echoed in `not_found_identifiers` rather than
            producing an error status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupRecordResponseSchema'
        '400':
          description: |
            Refused by the gateway (`VALIDATION_ERROR`): `identifiers` missing,
            one of them empty or blank or longer than 2048 characters, more than
            10 of them, or `connectorName` empty or sent more than once.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, invalid, expired, or revoked authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: OAuth token is missing both the `kb:read` and `connector:read` scopes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The authenticated user could not be resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error while resolving identifiers.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Connector service unavailable or connection refused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}/resync:
    post:
      tags:
      - Connector Instances
      summary: Resync connector
      description: |
        Trigger a resync of records from a connector instance.

        **Overview:**

        Fetches content from the external source and updates local records. Use when you suspect data is out of sync.

        Only a connector in the caller's list of active connectors
        (`GET /connectors/active`, knowledge bases included) can be resynced.
        Any other ID, including one that does not exist, is refused with `400`.
        The reply only acknowledges that the resync event was published.

        Fields of the body other than `connectorName` and `fullSync` are dropped without an error.

        **Warning:** This can be resource-intensive for large connectors.

        The scope check also accepts `kb:write` in place of `connector:write`.
      operationId: resyncConnector
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
        - connector:read
      parameters:
      - name: connectorId
        in: path
        required: true
        description: |
          Connector instance ID. An ID that decodes to a path separator or
          another unsafe segment is refused with `400` before the token is checked.
        schema:
          type: string
      requestBody:
        required: true
        description: Request body for resync connector
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResyncConnectorRequestBody'
      responses:
        '200':
          description: Resync queued
          content:
            application/json:
              schema:
                type: object
                required:
                - resyncConnectorResponse
                properties:
                  resyncConnectorResponse:
                    type: object
                    description: Acknowledgement that the sync was queued.
                    required:
                    - success
                    properties:
                      success:
                        type: boolean
                        description: Whether the resync event was published
        '400':
          description: |
            The connector's sync is off or the connector doesn't exist (both
            answered as "not allowed"), or the body failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            The token lacks a required scope, or the connector is someone else's personal
            connector ("Only the person who created this connector can sync it"), checked
            before the lock and desktop checks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            Conflict. Possible reasons:<br>
            <ul>
            <li>A sync is already running, or the connector is locked</li>
            <li><code>DESKTOP_OFFLINE</code> - Local FS: the owner device's desktop app is not connected</li>
            <li><code>DESKTOP_UNCLAIMED</code> - Local FS: no device owns the connector yet</li>
            </ul>
            Local FS refusals carry <code>details.code</code> and use the
            LocalFsDesktopRefusal body; the others use the standard error body.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/LocalFsDesktopRefusal'
                - $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error, for example when the JSON body is not an object

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: |
            The sync event could not be published to the message broker, so
            nothing was queued or synced ("We couldn't start this sync because
            PipesHub couldn't queue it. Nothing was synced. Try again in a
            minute; ...").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}/sync/stop:
    post:
      tags:
      - Connector Instances
      summary: Stop the running sync for a connector
      description: |
        Ask the in-flight sync for a connector instance to stop.

        **Overview:**

        Returns as soon as the request is recorded; the sync halts at its next
        interruptible point, which for a connector inside a long provider call
        is when that call returns. `stopped` reports whether a sync was actually
        running, and `false` is a normal answer rather than a failure.

        Deliberately not refused while the connector is busy or locked: this is
        the endpoint that has to work precisely then, including against a lock a
        crashed process left behind. When nothing is running it also repairs a
        stale SYNCING or FULL_SYNCING status, unless the service cannot tell a
        live sync on another worker from a stale one, in which case it changes
        nothing and says so.
      operationId: stopConnectorSync
      security:
      - bearerAuth: []
      - oauth2:
        - connector:sync
      parameters:
      - name: connectorId
        in: path
        required: true
        description: Connector instance ID
        schema:
          type: string
      responses:
        '200':
          description: Stop recorded, or nothing was running
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - stopped
                - status
                - message
                properties:
                  success:
                    type: boolean
                  stopped:
                    type: boolean
                    description: Whether a sync was running and has been asked to stop. False is a normal answer, not an error.
                  status:
                    type: string
                    description: The status the connector is actually left in.
                    enum:
                    - IDLE
                    - SYNCING
                    - FULL_SYNCING
                    - QUEUED
                    - DELETING
                  message:
                    type: string
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Insufficient scope (connector:sync is required).
            Also returned for an instance of a beta connector type (Calendar, Meet,
            Forms, Slides, Docs, Zendesk, Airtable) while the platform feature flag
            `ENABLE_BETA_CONNECTORS` is off (the default), with the message
            `Beta connectors are not enabled. The connector '<type>' is a beta connector and cannot be accessed. ...`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Connector instance not found or not accessible. A team connector of
            another user is answered `404` to a member, as if it did not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: |
            The connector ID is not 1-64 letters, digits, `_` or `-`
            (`VALIDATION_ERROR`), or it decodes to an unsafe path segment
            (refused before the token is checked).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The stop could not be recorded.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}/config:
    get:
      tags:
      - Connector Configuration
      summary: Get connector configuration
      description: |
        Get the current configuration for a connector instance.<br><br>
        <b>Security:</b><br>
        Stored credentials and OAuth tokens (<code>credentials</code>, <code>oauth</code>)
        are never returned. The saved <code>auth</code> values are returned so the
        form can be edited, except that each secret (an <code>isSecret</code> or
        <code>PASSWORD</code> field of the connector type's auth schema, and a
        legacy <code>private_key</code>) comes back as <code>••••••••</code>.
        Sending that mask back on a save keeps the stored value. A personal connector's configuration is only
        readable by its creator: to anyone else, admins included, it is
        answered `404` as if it did not exist. A team connector of another
        user is answered `404` to a member.
      operationId: getConnectorConfig
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: connectorId
        in: path
        required: true
        description: Connector instance ID
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
      responses:
        '200':
          description: Saved configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  config:
                    $ref: '#/components/schemas/ConnectorConfig'
                required:
                - success
                - config
        '400':
          description: |
            Invalid request: a parameter or the body failed validation

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The configuration could not be read.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - Connector Configuration
      summary: Update connector configuration
      description: |
        Update authentication, sync, and filter configuration.<br><br>
        <b>Prerequisites:</b><br>
        Connector must be <b>disabled</b> before updating configuration.
        Disable it first using <code>POST /{id}/toggle</code>.<br><br>
        <b>Partial Updates:</b><br>
        Only provide the sections you want to update. Omitted sections
        are not modified.<br><br>
        <b>Secrets:</b><br>
        A secret field in <code>auth</code> sent as <code>••••••••</code> keeps the
        stored value, so the configuration can be sent back as it was read. The
        response masks stored secrets the same way.<br><br>
        <b>Signing out:</b><br>
        A change to <code>auth</code>, a different top-level <code>oauthConfigId</code>,
        or a linked OAuth app that now holds a different client signs the connector
        out and clears its OAuth tokens. Sending <code>auth</code> back as it was read,
        with secrets as the mask or in full, keeps it signed in.<br><br>
        <b>OAuth apps (OAUTH connectors):</b><br>
        An OAUTH connector signs in with the client ID and secret of its linked OAuth
        app, so client credentials an admin sends in <code>auth</code> go into an app,
        as on <code>PUT /{connectorId}/config/auth</code>:
        <ul>
          <li>On a connector with no app, an app is created from them and linked
          (<code>auth.oauthConfigId</code> in the response) once every required OAuth
          field is present; until then the values are kept on the connector.</li>
          <li>On a linked connector, changed values update the app named in
          <code>auth.oauthConfigId</code>, and only the fields that changed. Without that
          field a new app is created and linked; the previously linked app, which other
          connectors may share, is not changed.</li>
          <li>The new app is named <code>auth.oauthInstanceName</code>, or else after the
          connector.</li>
        </ul>
        A linked connector stores no copy of its app's secret fields: they are not
        stored, and not returned, in <code>config.auth</code>. Its client ID and provider
        URLs are the app's. Only an admin's credentials create or change an app.
      operationId: updateConnectorConfig
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
        - connector:read
      parameters:
      - name: connectorId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectorConfigRequest'
      responses:
        '200':
          description: Configuration updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  config:
                    $ref: '#/components/schemas/ConnectorStoredConfig'
                  message:
                    type: string
                    example: Configuration saved successfully.
                required:
                - success
                - config
        '400':
          description: |
            Refused. Possible reasons:<br>
            <ul>
            <li><code>VALIDATION_ERROR</code> - <code>baseUrl</code> is not a string</li>
            <li><code>filters.sync</code> or <code>filters.indexing</code> is present but not an object</li>
            <li><code>auth</code> is present but not an object ("Auth configuration must be an object.")</li>
            <li><code>auth.authType</code> differs from the instance's auth type, which is locked after creation</li>
            <li>A required sync filter of the connector type is not set</li>
            <li>The connector is active: disable it before updating</li>
            <li>The connector ID is an unsafe path segment</li>
            <li>For an OAUTH connector: a new client ID sent without its client secret; a replacement OAuth app that would lack a required field; or a client secret sent while the connector still lacks its own authorize and token URLs (ServiceNow). Nothing is stored.</li>
            </ul>
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: |
            Connector, or the OAuth app named in <code>auth.oauthConfigId</code>, not found.
            For the connector: also when it is not visible to the caller (another user's
            personal connector, or another user's team connector for a member).
            Also the answer for an ID of the wrong shape: this route does not check it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: |
            The connector is locked by a sync or deletion in progress, or an OAuth app
            with the name the new app would take already exists in the organization. For
            a name collision, send a different <code>auth.oauthInstanceName</code>, or name
            the app to update in <code>auth.oauthConfigId</code>.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The configuration, or the OAuth app, could not be saved. An app this request
            created is removed, and an app it updated is put back.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}/config/auth:
    put:
      tags:
      - Connector Configuration
      summary: Update authentication configuration
      description: |
        Update only the authentication configuration.<br><br>
        <b>Use Case:</b><br>
        Use this when you need to update credentials without changing
        sync or filter settings. Useful for credential rotation.<br><br>
        <b>Prerequisites:</b><br>
        Connector must be disabled. This endpoint clears OAuth state,
        requiring re-authentication for OAuth connectors.<br><br>
        <b>Secrets:</b><br>
        A secret field sent as <code>••••••••</code> keeps the stored value; send a
        new value to replace it. The response masks stored secrets the same way.
      operationId: updateConnectorAuthConfig
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
      parameters:
      - name: connectorId
        in: path
        required: true
        description: Connector instance ID
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectorAuthRequest'
      responses:
        '200':
          description: Auth settings saved. The connector is signed out and turned off.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  config:
                    $ref: '#/components/schemas/ConnectorStoredConfig'
                  message:
                    type: string
                    example: Authentication configuration saved successfully.
                required:
                - success
                - config
        '400':
          description: |
            Invalid auth settings, `auth` is not an object ("Auth configuration must be an object."),
            or the connector is active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The connector is locked by a sync or deletion in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error, for example when the body is not an object

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}/config/filters-sync:
    put:
      tags:
      - Connector Configuration
      summary: Update filters and sync configuration
      description: |
        Update filter selections and sync settings without touching auth.<br><br>
        <b>Use Case:</b><br>
        Use this to change what data is synced or adjust sync schedule
        without re-authenticating.<br><br>
        <b>Merging:</b><br>
        `sync` is merged key by key into the saved sync settings. Each of
        `filters.sync` and `filters.indexing` that is sent replaces the saved
        one. A `sync` or `filters` value that is not an object is skipped
        without an error. Fields other than `sync` and `filters`, `baseUrl`
        included, are dropped without an error.<br><br>
        The connector must be disabled (`400` otherwise).
      operationId: updateConnectorFiltersSyncConfig
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
        - connector:read
      parameters:
      - name: connectorId
        in: path
        required: true
        description: Connector instance ID
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConnectorFiltersSyncRequest'
      responses:
        '200':
          description: Sync and filter settings saved; the connector is configured
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  config:
                    $ref: '#/components/schemas/ConnectorStoredConfig'
                  message:
                    type: string
                  syncFiltersChanged:
                    type: boolean
                    description: The next sync is a full sync
                required:
                - success
                - config
        '400':
          description: |
            Invalid settings, a required sync filter is missing, `filters.sync` or `filters.indexing`
            is present but not an object ("filters.sync must be an object"), or the connector is active
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The connector is locked by a sync or deletion in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error, for example when the body or `filters` is not an object

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}/toggle:
    post:
      tags:
      - Connector Control
      summary: Toggle connector sync or agent
      description: |
        Flip a connector's sync or agent use: each call turns it on when it is off and
        off when it is on. Read <code>isActive</code> / <code>isAgentActive</code> first. Turning sync on
        starts the first sync.<br><br>
        <b>Toggle Types:</b><br>
        <ul>
        <li><code>sync</code> - data synchronization</li>
        <li><code>agent</code> - use by AI agents</li>
        </ul>
        <b>Before Sync Can Be Turned On:</b><br>
        <ul>
        <li>The connector is configured (<code>isConfigured: true</code>)</li>
        <li>OAuth connectors: sign-in has completed</li>
        <li>The connection test against the source passes</li>
        <li>For agent: the connector supports agents (<code>supportsAgent: true</code>)</li>
        <li>Local FS: must be enabled from the owner device via the desktop app, which sends <code>deviceId</code> and <code>deviceName</code>. The first enable claims that device as owner.</li>
        </ul>
        <b>Permissions:</b><br>
        <ul>
        <li>Team scope: Requires admin</li>
        <li>Personal scope: Only creator can toggle</li>
        </ul>
      operationId: toggleConnector
      security:
      - bearerAuth: []
      - oauth2:
        - connector:sync
        - connector:read
      parameters:
      - name: connectorId
        in: path
        required: true
        description: Connector instance ID
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorToggleRequest'
      responses:
        '200':
          description: Flipped
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                required:
                - success
        '400':
          description: 'Invalid body, or the connector cannot be turned on yet: OAuth sign-in is not complete, it is not configured, or its connection test failed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: A Local FS desktop refusal, or the connector is locked
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/LocalFsDesktopRefusal'
                - $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error, for example when the JSON body is not an object

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}/oauth/authorize:
    get:
      tags:
      - Connector OAuth
      summary: Get OAuth authorization URL
      description: |
        Start the OAuth sign-in for a connector instance.<br><br>
        <b>Flow:</b><br>
        <ol>
        <li>Call this endpoint to get <code>authorizationUrl</code> and <code>state</code></li>
        <li>A person opens the URL and gives consent at the provider</li>
        <li>The provider redirects to <code>{baseUrl}/{redirectUri}</code> with <code>code</code> and <code>state</code></li>
        <li>Pass both to <code>GET /connectors/oauth/callback</code> with a bearer token</li>
        </ol>
        The redirect URI is fixed when the connector is created (its <code>baseUrl</code>) and must be
        registered with the provider.
      operationId: getOAuthAuthorizationUrl
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
      parameters:
      - name: connectorId
        in: path
        required: true
        description: Connector instance ID
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
      - name: desktop
        in: query
        required: false
        description: |
          `true` when the sign-in starts in the desktop app: the `state` sent to the provider is
          marked so the web callback page hands `code` and `state` to the app over a `pipeshub://`
          link instead of finishing the sign-in in the browser. Any other value is ignored.
        schema:
          type: string
      responses:
        '200':
          description: Provider consent URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  authorizationUrl:
                    type: string
                    description: Open in a browser to give consent
                  state:
                    type: string
                    description: Pass back with the provider's code to the callback
                required:
                - success
                - authorizationUrl
                - state
        '400':
          description: |
            The connector does not use OAuth, or its OAuth app is missing

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error, for example when the saved `oauthConfigId` is not a string

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/oauth/callback:
    get:
      tags:
      - Connector OAuth
      summary: OAuth callback handler
      description: |
        Finish the OAuth sign-in: exchange the provider's <code>code</code> for tokens and store
        them. Call it with the <code>code</code> and <code>state</code> the provider sent to the redirect URI,
        as the connector's creator or an admin.<br><br>
        <b>Result:</b><br>
        Always JSON. <code>success</code> is true when the connector is signed in; otherwise
        <code>error</code> and <code>errorMessage</code> say why. Provider tokens are never returned.
      operationId: handleOAuthCallback
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
      parameters:
      - name: code
        in: query
        required: true
        description: |
          Authorization code from provider. A missing, empty or blank value is
          refused with `400`, even when the provider only sent `error`.
        schema:
          type: string
          minLength: 1
          pattern: \S
      - name: state
        in: query
        required: true
        description: State parameter (contains connector ID). A missing, empty or blank value is refused with `400`.
        schema:
          type: string
          minLength: 1
          pattern: \S
      - name: error
        in: query
        description: Error code if authorization failed
        schema:
          type: string
      - name: baseUrl
        in: query
        description: Origin prefixed to the returned `redirectUrl`
        schema:
          type: string
      responses:
        '200':
          description: Result of exchanging the code. `success` is false when the provider refused it.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether tokens were stored and the connector is authenticated
                  redirectUrl:
                    type: string
                    description: Where the web app would send the user next
                    example: https://pipeshub.mycompany.com/connectors/oauth/callback?oauth_error=access_denied
                  error:
                    type: string
                    description: |
                      Only when `success` is `false`. The provider's own code when
                      it was passed in `error`, otherwise one of `invalid_state`,
                      `instance_not_found`, `config_not_found`,
                      `oauth_config_fetch_error`, `invalid_token` or `server_error`.
                    example: access_denied
                  errorMessage:
                    type: string
                    description: Only when `error` is `server_error`. A readable reason for the failed token exchange.
                required:
                - success
        '400':
          description: |
            Invalid request: a parameter or the body failed validation

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}/filters:
    get:
      tags:
      - Connector Filters
      summary: Get filter options
      description: |
        Get available filter options for a connector.<br><br>
        <b>Overview:</b><br>
        Returns filter fields that can be used to limit what data is synced.
        For example, a Google Drive connector might offer filters for
        specific folders or file types.<br><br>
        <b>Dynamic Filters:</b><br>
        Some filter fields have <code>dynamic: true</code> (i.e.
        <code>optionSourceType: dynamic</code>), meaning their options are
        loaded separately via the filter options endpoint.
        For such fields, call
        <code>GET /connectors/{connectorId}/filters/{filterKey}/options</code>.
        When scoping options to a specific parent (e.g. GitLab projects within
        a selected group), pass the parent paths via the
        <code>contextGroupPath</code> query parameter on that endpoint.<br><br>
        <b>Which connectors answer:</b><br>
        An <code>OAUTH</code> connector answers once it has completed sign-in. A connector with
        any other auth type (<code>API_TOKEN</code>, <code>BEARER_TOKEN</code>,
        <code>OAUTH_ADMIN_CONSENT</code>, <code>BASIC_AUTH</code>, <code>ACCESS_KEY</code>,
        <code>ACCOUNT_KEY</code>, <code>CONNECTION_STRING</code>, <code>ENTRA_ID</code>, <code>CUSTOM</code>) answers once its settings,
        including the auth section, are saved. A <code>NONE</code> connector (for example RSS)
        needs saved settings but no auth section. Otherwise the request is refused with
        <code>400</code>.
      operationId: getConnectorFilters
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: connectorId
        in: path
        required: true
        description: |
          Connector instance ID: 1-64 letters, digits, `_` or `-`
          (`400 VALIDATION_ERROR` otherwise). An ID that decodes to an unsafe
          path segment is refused with `400` before the token is checked.
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
      responses:
        '200':
          description: |
            Filter options retrieved. A connector whose auth type has no dynamic filter options
            (for example <code>NONE</code> or <code>BASIC_AUTH</code>) and has saved settings gets an
            empty <code>filterOptions</code> object.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  filterOptions:
                    $ref: '#/components/schemas/FilterOptions'
                required:
                - success
                - filterOptions
        '400':
          description: |
            An OAUTH connector has not signed in, or another connector has no saved settings
            (or, for any type except <code>NONE</code>, no saved auth section).

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden — one of:
            - the OAuth token lacks the `connector:read` scope
            - the token lacks <code>connector:read</code>, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The filter options could not be read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      deprecated: true
      x-speakeasy-deprecation-message: 'Use PUT /connectors/{connectorId}/config/filters-sync instead, with a body of {sync?, filters?: {sync, indexing}} (the flat filters map this route takes is ignored there: the call returns 200 and saves none of it), and only while the connector is disabled. This endpoint will be removed in a future release.'
      tags:
      - Connector Filters
      summary: Save filter selections (deprecated)
      description: |
        <b>Deprecated.</b> Save filters with
        <code>PUT /connectors/{connectorId}/config/filters-sync</code> instead, which is what the
        PipesHub app uses. That route takes <code>{sync?, filters?: {sync, indexing}}</code>. It ignores the
        flat <code>filters</code> map this one takes: the call still returns 200, but nothing is saved.
        It also refuses while the connector is active, so disable it first.
        This endpoint will be removed in a future release.<br><br>
        What this endpoint saves goes to <code>filters.values</code>, which sync does not read:
        sync reads <code>filters.sync</code> and <code>filters.indexing</code>.<br><br>
        Save the user's filter selections for a connector.<br><br>
        <b>Request:</b><br>
        <code>filters</code> must hold at least one entry: <code>{"filters": {}}</code> is
        refused with <code>400</code>. The server stores whatever it is given under the
        connector's saved filter values without checking it against the filter schema.
        Use <code>PUT /connectors/{connectorId}/config/filters-sync</code> to save typed
        sync and indexing filters.
      operationId: saveConnectorFilters
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
      parameters:
      - name: connectorId
        in: path
        required: true
        description: |
          Connector instance ID. Unlike `GET` on this path, not checked for
          shape: an ID that matches no instance is a `404`. An ID that decodes
          to an unsafe path segment is refused with `400` before the token is checked.
        schema:
          type: string
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SaveConnectorFiltersRequest'
      responses:
        '200':
          description: Filters saved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                required:
                - success
                - message
        '400':
          description: <code>filters</code> is missing or empty
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden — one of:
            - the OAuth token lacks the `connector:write` scope
            - the token lacks <code>connector:write</code>, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The connector is locked by a sync or deletion in progress
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The selections could not be saved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /connectors/{connectorId}/filters/{filterKey}/options:
    get:
      tags:
      - Connector Filters
      summary: Get dynamic filter options
      description: |
        Get options for a dynamic filter field with pagination.<br><br>
        <b>Overview:</b><br>
        For filters with <code>optionSourceType: dynamic</code>, options are loaded
        from the connected service. This supports pagination and search. The
        connector is started on demand with its saved credentials, so the
        connected service must be reachable.<br><br>
        <b>Scoped options (GitLab):</b><br>
        When fetching options for the <code>project_ids</code> filter key, pass
        one or more <code>contextGroupPath</code> query parameters to restrict
        the returned repositories to those that belong to the specified GitLab
        group namespace paths (e.g. <code>myorg/team</code>). This is used to
        populate the project filter after the user has selected groups. Other
        connectors accept and ignore both group path parameters.<br><br>
        <b>Examples:</b><br>
        <ul>
        <li>Google Drive folders list</li>
        <li>Slack channels list</li>
        <li>Confluence spaces list</li>
        <li>GitLab groups list (<code>filterKey=group_ids</code>)</li>
        <li>GitLab projects scoped to groups (<code>filterKey=project_ids&amp;contextGroupPath=myorg/team</code>)</li>
        </ul>
        Query parameters other than the six below are dropped without an error.
      operationId: getFilterFieldOptions
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: connectorId
        in: path
        required: true
        description: Connector instance ID
        schema:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,64}$
      - name: filterKey
        in: path
        required: true
        description: |
          Filter field key, the `name` of a field in the connector type's
          `config.filters` (`GET /connectors/registry/{connectorType}/schema`).
          An unsafe path segment is refused with `400` before the token is checked.
        schema:
          type: string
          pattern: ^(?!\.{1,2}$)[^/\\?#%\x00-\x1f\x7f]+$
        example: buckets
      - name: page
        in: query
        description: Page number. An empty value is refused.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        description: |
          Page size, 1 to 100. A value above 100 or an empty value is refused
          by the gateway's validator ("Limit must be between 1 and 100.").
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: search
        in: query
        description: Search term for filtering options
        schema:
          type: string
      - name: cursor
        in: query
        description: Cursor for cursor-based pagination, passed on to connectors that page by cursor
        schema:
          type: string
      - name: contextGroupPath
        in: query
        description: |
          One or more GitLab group namespace paths (e.g. `myorg/team`).
          When provided for the `project_ids` filter key, the returned
          options are scoped to repositories that belong to those groups.
          Repeat the parameter for multiple groups:
          `?contextGroupPath=groupA&contextGroupPath=groupB`. Blank values
          are dropped.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      - name: excludeContextGroupPath
        in: query
        description: |
          One or more GitLab group namespace paths to exclude. When provided
          for the `project_ids` filter key, the returned options omit
          repositories that belong to those groups (used when the
          `group_ids` sync filter is `not_in`). Repeat the parameter for
          multiple groups:
          `?excludeContextGroupPath=groupA&excludeContextGroupPath=groupB`.
          Blank values are dropped.
        schema:
          type: array
          items:
            type: string
        style: form
        explode: true
      responses:
        '200':
          description: Filter options
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  options:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Value to store in the filter selection
                        label:
                          type: string
                          description: Text shown for the option
                  page:
                    type: integer
                  limit:
                    type: integer
                  hasMore:
                    type: boolean
                  cursor:
                    type: string
                    description: Pass back to get the next page
                    nullable: true
                  message:
                    type: string
                    nullable: true
                    description: Informational message, only when the connector sets one
                required:
                - success
                - options
        '400':
          description: |
            Invalid parameters, the filter is not dynamic, or an OAuth connector is not signed in

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Unknown connector or filter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The connected service could not be queried.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /oauth/registry:
    get:
      tags:
      - OAuth Configuration
      summary: List OAuth-capable connector types
      description: |
        List the connector and toolset types that support OAuth, from the OAuth registry.<br><br>
        Each entry carries the provider URLs, the scopes requested, and the `authFields`
        to collect when creating an OAuth configuration for that type.<br><br>
        Any authenticated user can call this; it is not limited to admins.
      operationId: getOAuthRegistry
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
      - name: search
        in: query
        description: Matches the connector type's name, group or description
        schema:
          type: string
      responses:
        '200':
          description: OAuth connector types retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  connectors:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthRegistryEntry'
                  pagination:
                    $ref: '#/components/schemas/OAuthRegistryPagination'
                required:
                - success
                - connectors
                - pagination
        '400':
          description: |
            Invalid request: a parameter or the body failed validation

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden — one of:
            - the OAuth token lacks the `connector:read` scope
            - the token lacks `connector:read`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The registry could not be read.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /oauth/registry/{connectorType}:
    get:
      tags:
      - OAuth Configuration
      summary: Get OAuth connector type details
      description: |
        Get the OAuth registry entry of one connector or toolset type.<br><br>
        `connectorType` is the registered name and is case-sensitive (e.g. `Confluence`).
      operationId: getOAuthConnectorType
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: connectorType
        in: path
        required: true
        description: Registered name of the type, case-sensitive
        schema:
          type: string
        example: Confluence
      - name: page
        in: query
        description: Validated like the `page` of `GET /oauth/registry`, then ignored; the reply is the same with or without it.
        schema:
          type: integer
          minimum: 1
      - name: limit
        in: query
        description: Validated like the `limit` of `GET /oauth/registry`, then ignored.
        schema:
          type: integer
          minimum: 1
          maximum: 200
      - name: search
        in: query
        description: Validated as a single text value, then ignored.
        schema:
          type: string
      responses:
        '200':
          description: Connector type retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  connector:
                    $ref: '#/components/schemas/OAuthRegistryEntry'
                required:
                - success
                - connector
        '400':
          description: |
            Bad request — `connectorType` is not a safe path segment, or a `page`, `limit` or `search`
            query parameter was sent and fails validation: `page` or `limit` out of range, not a whole
            number or empty, or any of the three sent more than once (the route validates them although
            it does not use them)

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden — one of:
            - the OAuth token lacks the `connector:read` scope
            - the token lacks `connector:read`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The connector type has no OAuth app registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The registry could not be read.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /oauth:
    get:
      tags:
      - OAuth Configuration
      summary: List OAuth configurations
      description: |
        List the saved OAuth apps of every connector type in the organization.<br><br>
        Every caller, admin or not, gets the same essential fields (ID, name, connector type, app
        metadata, timestamps). Credentials are never included; an admin reads them per app with
        <code>GET /oauth/{connectorType}/{configId}</code>.
      operationId: listOAuthConfigs
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
      - name: search
        in: query
        description: Case-insensitive substring matched against the name, connector type, group, description and categories
        schema:
          type: string
      responses:
        '200':
          description: OAuth apps of every connector type
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  oauthConfigs:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthConfig'
                  pagination:
                    $ref: '#/components/schemas/OAuthConfigPagination'
                required:
                - success
                - oauthConfigs
                - pagination
        '400':
          description: |
            Invalid request: a parameter or the body failed validation

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The configurations could not be loaded.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /oauth/{connectorType}:
    get:
      tags:
      - OAuth Configuration
      summary: List OAuth configs for connector type
      description: |
        List the organization's OAuth configurations for one connector type.<br><br>
        <b>What comes back depends on the caller:</b><br>
        <ul>
        <li>An admin gets each stored record in full, including `config` with the client secret in clear text</li>
        <li>Any other caller gets only the credential-free fields</li>
        </ul>
        A connector type with no configurations, or one that does not exist, yields an empty list.
      operationId: listOAuthConfigsByType
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: connectorType
        in: path
        required: true
        schema:
          type: string
        example: Confluence
      - name: scope
        in: query
        required: false
        description: Only OAuth apps usable for this connector scope
        schema:
          $ref: '#/components/schemas/ConnectorScope'
      - name: page
        in: query
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 20
      - name: search
        in: query
        description: Space-separated terms; every term must appear in the name, connector type, group, description or categories
        schema:
          type: string
      - $ref: '#/components/parameters/RevealStoredSecrets'
      responses:
        '200':
          description: Saved OAuth apps
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  oauthConfigs:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAuthConfigRecord'
                  pagination:
                    $ref: '#/components/schemas/OAuthRegistryPagination'
                required:
                - success
                - oauthConfigs
        '400':
          description: |
            Invalid request: a parameter or the body failed validation

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The configurations could not be loaded.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      tags:
      - OAuth Configuration
      summary: Create OAuth configuration
      description: |
        Create a new OAuth configuration for a connector type.<br><br>
        <b>Admin Only:</b><br>
        Only admins can create OAuth configurations. These provide the
        OAuth credentials needed for users to authenticate connectors.<br><br>
        <b>Use Case:</b><br>
        Before users can create Google Drive connectors with OAuth,
        an admin must create an OAuth configuration with the Google
        OAuth client ID and secret.<br><br>
        The response carries the credential-free view of the new configuration; the
        credentials are never echoed back. Success is reported as `200`, not `201`.<br><br>
        <b>The connector type is not checked.</b> `connectorType` is not compared with the OAuth
        registry, so a misspelled or wrongly-cased name (`confluence` for `Confluence`) does not
        fail: the configuration is stored under that name with the default icon and an empty
        group, description and category list. It is then returned by
        `GET /oauth/{connectorType}` for that same name but never by `GET /oauth`, which only
        walks the registered types.<br><br>
        Body fields other than `oauthInstanceName`, `config` and `baseUrl` are ignored.
      operationId: createOAuthConfig
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
      parameters:
      - name: connectorType
        in: path
        required: true
        schema:
          type: string
        example: Confluence
      requestBody:
        required: true
        description: Request payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOAuthConfigRequest'
      responses:
        '200':
          description: OAuth configuration created
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - oauthConfig
                - message
                properties:
                  success:
                    type: boolean
                  oauthConfig:
                    $ref: '#/components/schemas/OAuthConfig'
                  message:
                    type: string
                    example: OAuth configuration created successfully
        '400':
          description: |
            Invalid request: `oauthInstanceName` or `config` is missing or empty.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden — one of:
            - the OAuth token lacks the `connector:write` scope
            - the token lacks `connector:write`, or the caller is not an admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Another of the org's OAuth apps for this connector type already has this `oauthInstanceName`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error, for example when the JSON body is not an object

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /oauth/{connectorType}/{configId}:
    get:
      tags:
      - OAuth Configuration
      summary: Get OAuth configuration
      description: |
        Get a specific OAuth configuration by ID.<br><br>
        An admin gets `config` with the stored credentials, client secret in clear text.
        Any other caller gets the same object without `config`.
      operationId: getOAuthConfig
      security:
      - bearerAuth: []
      - oauth2:
        - connector:read
      parameters:
      - name: connectorType
        in: path
        required: true
        schema:
          type: string
        example: Confluence
      - name: configId
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/RevealStoredSecrets'
      responses:
        '200':
          description: Saved OAuth app
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  oauthConfig:
                    $ref: '#/components/schemas/OAuthConfigWithCredentials'
                required:
                - success
                - oauthConfig
        '400':
          description: |
            Invalid request: a parameter or the body failed validation

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The token lacks a required scope, or the caller may not use this connector
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The configuration could not be loaded.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - OAuth Configuration
      summary: Update OAuth configuration
      description: |
        Update an OAuth configuration.<br><br>
        <b>Admin Only:</b><br>
        Only an admin can update, including apps another admin created.
      operationId: updateOAuthConfig
      security:
      - bearerAuth: []
      - oauth2:
        - connector:write
      parameters:
      - name: connectorType
        in: path
        required: true
        schema:
          type: string
        example: Confluence
      - name: configId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        description: |
          Send `oauthInstanceName`, `config`, or both; a body with neither is
          refused, even if it carries `baseUrl`.
        content:
          application/json:
            schema:
              type: object
              anyOf:
              - required:
                - oauthInstanceName
              - required:
                - config
              properties:
                oauthInstanceName:
                  type: string
                  minLength: 1
                  description: New name; must not be taken by another of the org's apps for this connector type.
                  pattern: \S
                config:
                  type: object
                  description: |
                    OAuth app fields to change, merged over the saved ones. Keys follow
                    the connector type's OAuth fields; a masked secret sent back as
                    returned is ignored, so the saved value is kept.
                  additionalProperties: true
                  properties:
                    clientId:
                      type: string
                    clientSecret:
                      type: string
                    tenantId:
                      type: string
                baseUrl:
                  type: string
                  description: PipesHub's public origin. Used only when the stored configuration has no redirectUri yet, to build one; an existing redirectUri is kept whether or not this is sent.
              description: At least one of `oauthInstanceName` and `config` must be present. Other fields are ignored.
      responses:
        '200':
          description: OAuth configuration updated
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - oauthConfig
                - message
                properties:
                  success:
                    type: boolean
                  oauthConfig:
                    $ref: '#/components/schemas/OAuthConfig'
                  message:
                    type: string
                    example: OAuth configuration updated successfully
        '400':
          description: |
            Invalid configuration: neither `oauthInstanceName` nor `config` was
            sent, or `oauthInstanceName` is empty.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden — one of:
            - the OAuth token lacks the `connector:write` scope
            - the token lacks `connector:write`, or the caller is not an admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Configuration not found for this connector type in the caller's organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Another of the org's OAuth apps for this connector type already has the new `oauthInstanceName`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal error, for example when the JSON body is not an object

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
      - OAuth Configuration
      summary: Delete OAuth configuration
      description: |
        Delete an OAuth configuration.<br><br>
        <b>Admin Only:</b><br>
        Only admins can delete OAuth configurations.<br><br>
        <b>Warning:</b><br>
        The server does not check whether connectors still use the configuration:
        it is deleted either way, and those connectors lose their OAuth app.
      operationId: deleteOAuthConfig
      security:
      - bearerAuth: []
      - oauth2:
        - connector:delete
      parameters:
      - name: connectorType
        in: path
        required: true
        schema:
          type: string
        example: Confluence
      - name: configId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OAuth configuration deleted
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - message
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                    example: OAuth configuration 38c772e6-9ce3-4bd6-907d-b7f5302c1fcf deleted successfully
        '400':
          $ref: '#/components/responses/XssRejected'
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Forbidden — one of:
            - the OAuth token lacks the `connector:delete` scope
            - the token lacks `connector:delete`, or the caller is not an admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Configuration not found, or the caller has no access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            The configuration could not be deleted.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /configurationManager/ai-models/available/{modelType}:
    get:
      tags:
      - AI Models Providers
      summary: Get available models by type
      description: |
        Returns a **flattened list** of individual AI models of the requested type,
        suitable for use in selection dropdowns and model-picker UIs.

        Each provider configuration entry may specify multiple comma-separated model
        names; this endpoint expands those into one object per model name so callers
        receive a flat, enumerable collection.

        **Flattening rules:**
        - Only the **first** model in a multi-model provider entry is marked
          `isDefault: true`; all subsequent models from the same entry get `false`.
        - `modelFriendlyName` is included **only** when the provider entry contains
          exactly one model name (not a comma-separated list).
        - `defaultReasoningEffort` is included on every model of an entry whose
          `configuration.defaultReasoningEffort` (or, when that is unset, a
          top-level `defaultReasoningEffort`) holds a valid effort. It is left out
          when no default is stored.
        - When no providers of the requested type are configured the endpoint still
          returns HTTP **200** with an empty `models` array — this is **not** an error.

        **Access control:** requires a valid bearer token, from any member of the
        organization (there is no admin check). For OAuth tokens the `config:read` scope
        must be present; regular JWT bearer tokens pass through without scope enforcement.
        The query string is not read.
      operationId: getAvailableModelsByType
      security:
      - bearerAuth: []
      - oauth2:
        - config:read
      parameters:
      - name: modelType
        in: path
        required: true
        description: |
          Category of AI model to retrieve.

          Must be one of: `llm`, `embedding`, `ocr`, `slm`, `reasoning`, `multiModal`, `imageGeneration`, `tts`, `stt`, `decision`.
        schema:
          $ref: '#/components/schemas/ModelType'
      responses:
        '200':
          description: |
            Available models retrieved successfully.

            An empty `models` array (with HTTP 200) is returned when no providers of
            the requested type have been configured — treat this as a valid, empty
            state, not an error.
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - models
                - message
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    example: success
                  message:
                    type: string
                    description: |-
                      Human-readable summary. Two formats are possible:
                      - `"Found {n} {modelType} models"` — the `modelType` key
                        exists in the stored config (returned even when `n` is 0,
                        e.g. `"Found 0 ocr models"`).

                      - `"No {modelType} models found"` — no AI config has been
                        stored yet, or the `modelType` key is absent from the
                        stored config entirely.
                    example: Found 2 llm models
                  models:
                    type: array
                    description: Flat list of individual model entries. Each entry represents one model name from one provider configuration.
                    items:
                      type: object
                      required:
                      - modelType
                      - provider
                      - modelName
                      - isMultimodal
                      - isReasoning
                      - isDefault
                      properties:
                        modelType:
                          allOf:
                          - $ref: '#/components/schemas/ModelType'
                          description: Model category — always matches the `{modelType}` path parameter.
                        provider:
                          type: string
                          description: Provider identifier as stored in configuration (e.g. `openAI`, `azureOpenAI`, `anthropic`, `gemini`, `ollama`).
                          example: azureOpenAI
                        modelName:
                          type: string
                          description: Specific model name/identifier forwarded to the provider API when making inference calls.
                          example: gpt-5.6-luna
                        modelKey:
                          type: string
                          format: uuid
                          description: UUID that uniquely identifies the provider configuration entry this model was expanded from. Use this key when calling update/delete endpoints. Absent for an entry of a type other than `llm` or `embedding` that was saved through POST /configurationManager/aiModelsConfig, which gives a key only to `llm` and `embedding` entries; such an entry cannot be updated or deleted by key.
                          example: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
                        isMultimodal:
                          type: boolean
                          description: '`true` when this model accepts multi-modal inputs (text + images). Always present; defaults to `false` when not explicitly set.'
                          example: true
                        isReasoning:
                          type: boolean
                          description: '`true` when this is a reasoning / chain-of-thought model. Always present; defaults to `false` when not explicitly set.'
                          example: true
                        isDefault:
                          type: boolean
                          description: '`true` for the first model in the provider entry that was marked as default. At most one entry per `modelType` will have this set to `true`.'
                          example: true
                        modelFriendlyName:
                          type: string
                          description: Optional human-readable display name. Only present when the provider configuration entry contains exactly one model name (not a comma-separated list) **and** a friendly name was added during configuration.
                          example: Reasoning model
                        defaultReasoningEffort:
                          type: string
                          enum:
                          - none
                          - low
                          - medium
                          - high
                          - max
                          description: The model's own reasoning effort. It applies only when the chat request sets no `reasoningEffort` and the agent has no `defaultReasoningEffort`; a level the user picks always wins. Read from `configuration.defaultReasoningEffort`, falling back to a top-level `defaultReasoningEffort`. Present on every model expanded from the entry, and left out when no default is stored. `none` is a legacy value that runs as `low`.
                          example: low
              examples:
                two_llm_models:
                  summary: Two LLM models from an Azure OpenAI provider
                  value:
                    status: success
                    message: Found 2 llm models
                    models:
                    - modelType: llm
                      provider: azureOpenAI
                      modelName: gpt-5.6-luna
                      modelKey: f3a4b5b6-5b6c-4e85-9097-3202cfe696fc
                      isMultimodal: true
                      isReasoning: true
                      isDefault: true
                    - modelType: llm
                      provider: azureOpenAI
                      modelName: gpt-5.6-terra
                      modelKey: 7af8d3a7-ad2e-43a1-8716-ae95e4fbc888
                      isMultimodal: true
                      isReasoning: true
                      isDefault: false
                      modelFriendlyName: Reasoning model
                      defaultReasoningEffort: low
                no_models_configured:
                  summary: modelType key present in config but zero models after expansion
                  value:
                    status: success
                    message: Found 0 ocr models
                    models: []
        '400':
          description: |
            `VALIDATION_ERROR` naming `params.modelType`: the path parameter is not one of the
            supported model types. The validator answers before the handler runs.

            Also returned, before authentication, when a query value, or any string in a JSON or form-encoded body, looks like markup to the app-wide XSS filter: an HTML tag, a script tag, `<iframe`, `<object`, `<embed` or `<svg` tag, a word starting with `on` followed by `=` (meant for inline event handlers such as `onerror=`, it also catches plain text such as `one=1`), a `javascript:` or `data:text/html` URL, an encoded script tag (`&lt;script`, `%3cscript`), or any string longer than 100,000 characters (`HTTP_BAD_REQUEST`, "HTML tags, scripts, and XSS content are not allowed in ...", naming the field or query parameter; a string over 100,000 characters is refused as too long instead). A JSON body that does not parse is refused the same way, also before authentication (`HTTP_BAD_REQUEST`, "The request body is not valid JSON.").
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: VALIDATION_ERROR
                  message: 'Model type must be one of: llm, embedding, ocr, slm, reasoning, multiModal, imageGeneration, tts, stt, decision.'
                  metadata:
                    errors:
                    - field: params.modelType
                      message: 'Model type must be one of: llm, embedding, ocr, slm, reasoning, multiModal, imageGeneration, tts, stt, decision.'
                      code: INVALID_ENUM
                      value: ''
        '401':
          description: |
            Missing or invalid authentication token.

            The bearer token was absent, expired, malformed, or could not be
            verified by the auth middleware.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: |
            Insufficient OAuth scope: the OAuth token does not carry `config:read`. There is
            no admin check, so a member's session token is not refused.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /configurationManager/web-search:
    get:
      tags:
      - Web Search
      summary: Get all web search providers
      description: |
        Retrieve all configured web search providers and current web search settings.

        **Authentication:** Session JWT or OAuth 2.0 access token via `Authorization: Bearer`.
        OAuth tokens must include the `config:read` scope. Admin role is not required.

        **API keys:** for anyone who isn't an org admin, each provider's `configuration.apiKey`
        comes back as the placeholder `****************`, and so does `configuration.baseUrl`
        (admins always get the stored address). Admins get the stored key, unless the
        server hides secrets from everyone (`HIDE_SECRET_CONFIG=true`). When updating a provider,
        sending the placeholder back keeps the stored key.

        The built-in `duckduckgo` entry (never stored, empty `configuration`) is always listed
        first; it is the default when no stored provider is. With nothing stored, `message` is
        `No web search providers found` and the settings are the defaults. Of the query
        string only `reveal` is read.
      operationId: getWebSearchProviders
      security:
      - bearerAuth: []
      - oauth2:
        - config:read
      parameters:
      - $ref: '#/components/parameters/RevealStoredSecrets'
      responses:
        '200':
          description: Web search providers and settings retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebSearchProvidersResponse'
        '400':
          $ref: '#/components/responses/XssRejected'
        '401':
          description: Missing or invalid Bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — OAuth token missing `config:read` scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: |
            Internal server error.

            A JSON body larger than 10 MB, or a form-encoded body larger than 100 KB or with more than 1000 fields, is answered `413` by the app-wide body parsers instead, also before authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'