> ## Documentation Index > Fetch the complete documentation index at: https://docs.findable.net/llms.txt > Use this file to discover all available pages before exploring further. # Create a new chat > Creates a new chat configuration. The authenticated user becomes the owner. Requires admin, contributor, or page-owner role. Each entry in `dataSources[]` may include a `datasourceId` referencing a `DataSourceCatalog` entity. All `datasourceId` references are validated against the datasources catalog — invalid references return 400. ## OpenAPI ````yaml /api-reference/openapi.json post /chats openapi: 3.0.3 info: title: Findable API version: 3.2.38 description: > REST API for the Findable AI Assistant platform. ## Authentication All endpoints (except `/server/setup` and `/server/bootstrap`) require a valid **Azure AD / Entra ID Bearer token**. ### Obtaining a token 1. Register (or reuse) an **App Registration** in Azure Entra ID for your client. 2. Under **API Permissions**, add a delegated permission for the Findable server app: `api:///User.Read` 3. Acquire a token using MSAL (or any OAuth 2.0 library) with the following parameters: | Parameter | Value | |-----------|-------| | Authority | `https://login.microsoftonline.com/` | | Client ID | Your client app registration ID | | Scope | `api:///User.Read` | | Grant type | Authorization Code (interactive) or Client Credentials (daemon) | ### Example (MSAL Node.js) ```javascript const { ConfidentialClientApplication } = require("@azure/msal-node"); const cca = new ConfidentialClientApplication({ auth: { clientId: "", authority: "https://login.microsoftonline.com/", clientSecret: "", }, }); const result = await cca.acquireTokenByClientCredential({ scopes: ["api:///.default"], }); // Use result.accessToken in the Authorization header ``` ### Using the token Include the token in every request: ``` Authorization: Bearer ``` ### Roles Access is determined by Azure AD group membership configured in the application settings: - **Admin (Owner)**: Full access to all endpoints including admin operations - **Contributor**: Can create and manage chats, files, and content - **User**: Read access to entitled chats and resources contact: name: Findable Support license: name: Proprietary servers: - url: /server description: Application server (relative) security: - BearerAuth: [] tags: - name: AI description: Chat completion and AI generation endpoints - name: Chats description: Chat configuration CRUD with ACL enforcement - name: Settings description: Application settings and health - name: Files description: Blob storage file operations - name: Search description: Azure AI Search resource management - name: User description: User profile, feedback, chat logs, and preferences - name: Flows description: FlowEngine flow designer operations - name: Prompts description: Prompt template management - name: Pages description: Navigation page management - name: Admin description: Administrative operations (admin-only) - name: Bootstrap description: Bootstrap seed data operations (admin-only) - name: Setup description: Initial application setup (pre-auth) - name: Cosmos description: Generic Cosmos DB CRUD operations - name: Tools description: Tool providers, web search, and utility tools - name: MCP description: Model Context Protocol server management - name: Telemetry description: Version, health, and API permission checks - name: SharePoint description: SharePoint entitlement management - name: Data Platform description: Data platform connection management - name: Vector Stores description: Vector store provider operations - name: OneDrive description: OneDrive personal file storage operations - name: Jobs description: Background job and scheduler management - name: Memory description: User and organizational memory operations - name: Slack description: >- Slack bot interactions and webhooks (public, uses Slack signature verification) - name: Teams description: Microsoft Teams bot webhooks and interactions - name: Human Input description: Human-in-the-loop input requests for flow executions - name: Datasources description: Datasource catalog CRUD with ACL enforcement - name: Assignments description: >- Assignment lifecycle: inbox, sent, create, launch, complete, delegate, reject, reassign, remind, and recurring schedules. Experimental feature — requires experimental flag enabled. paths: /chats: post: tags: - Chats summary: Create a new chat description: > Creates a new chat configuration. The authenticated user becomes the owner. Requires admin, contributor, or page-owner role. Each entry in `dataSources[]` may include a `datasourceId` referencing a `DataSourceCatalog` entity. All `datasourceId` references are validated against the datasources catalog — invalid references return 400. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Chat' responses: '201': description: Chat created content: application/json: schema: $ref: '#/components/schemas/Chat' '400': description: Invalid datasourceId reference(s) in dataSources array '401': description: Not authenticated '403': description: Insufficient permissions '500': description: Server error components: schemas: Chat: type: object properties: scope: description: Access control model type: string enum: - personal - shared createdBy: description: UPN of the creator type: string isPublic: description: Allow public read access type: boolean owners: type: array items: type: object properties: id: type: string minLength: 1 type: type: string enum: - group - user displayName: type: string mail: type: string securityEnabled: type: boolean mailEnabled: type: boolean groupTypes: nullable: true type: array items: type: string groupType: type: string userPrincipalName: type: string jobTitle: type: string department: type: string officeLocation: type: string required: - id - type additionalProperties: {} contributors: type: array items: type: object properties: id: type: string minLength: 1 type: type: string enum: - group - user displayName: type: string mail: type: string securityEnabled: type: boolean mailEnabled: type: boolean groupTypes: nullable: true type: array items: type: string groupType: type: string userPrincipalName: type: string jobTitle: type: string department: type: string officeLocation: type: string required: - id - type additionalProperties: {} users: type: array items: type: object properties: id: type: string minLength: 1 type: type: string enum: - group - user displayName: type: string mail: type: string securityEnabled: type: boolean mailEnabled: type: boolean groupTypes: nullable: true type: array items: type: string groupType: type: string userPrincipalName: type: string jobTitle: type: string department: type: string officeLocation: type: string required: - id - type additionalProperties: {} inheritEntitlements: anyOf: - type: boolean - type: object properties: owners: type: boolean contributors: type: boolean users: type: boolean additionalProperties: false hideFromCatalog: description: >- Hide entity from user-facing recommendations and catalog/search surfaces (still accessible to owners/contributors/admins) type: boolean createdAt: description: ISO-8601 creation timestamp type: string updatedBy: type: string updatedAt: description: ISO-8601 update timestamp type: string id: type: string description: Chat ID (UUID) title: type: string description: type: string instructions: description: Markdown-formatted instructions displayed in the chat canvas type: string icon: description: MUI icon name for navigation display type: string dataSources: description: Array of data sources for multi-source RAG (empty = LLM only) type: array items: type: object properties: id: type: string description: Unique identifier for this source datasourceId: description: >- FK to DataSourceCatalog.id — links this config entry to a catalog datasource type: string indexName: type: string description: >- Azure Search index name (empty string for virtual sources like FLOW_RETRIEVER) searchEndpoint: description: Search endpoint ID (uses default if not set) type: string weight: description: 'Result weighting 0.0-1.0 (default: 1.0)' type: number maxResults: description: Max docs from this source type: integer filter: description: Static OData filter expression type: string label: description: Display name (e.g. "Company Docs", "My Files") type: string type: description: >- DATASOURCE_TYPE — determines storage, indexing, and retrieval behaviour type: string enum: - shared - personal - workspace - sharepoint - websearch - llmknowledge - flowretriever - vectorretriever enabled: description: 'Whether this source is active (default: true)' type: boolean enableAclFiltering: description: >- Enable native ACL filtering (requires index permissionFilterOption=enabled) type: boolean allowUserToggle: description: >- When true, end users can disable this source at runtime from the sidebar type: boolean allowUserWeightEdit: description: When true, end users can adjust the source weight at runtime type: boolean allowUserMaxResultsEdit: description: When true, end users can adjust max results at runtime type: boolean selectedFolder: description: >- Blob folder name for file-backed sources (e.g. "Company Docs/") type: string flowId: description: FK to IFlowDesignerFlow (when type === FLOW_RETRIEVER) type: string flowParams: description: >- Pre-configured inputs for the retriever flow (e.g. connectionId) type: object additionalProperties: {} lockedFlowParams: description: >- Variable names locked from end-user override (admin-only values) type: array items: type: string hiddenFlowParams: description: Optional variable names hidden from end users type: array items: type: string connectionMode: description: Derived from lockedFlowParams; kept for sidebar/backend compat type: string enum: - fixed - user - hybrid retrieverInstructions: description: >- NL instructions injected into the flow as {{_retrieverInstructions}} type: string vectorConnectionId: description: FK to IDataConnection (vector store connection) type: string vectorIndex: description: Index / collection / class name within the vector store type: string vectorTopK: description: Number of results (default 5) type: integer vectorSearchType: description: Search strategy for vector store type: string enum: - vector - semantic - hybrid - keyword vectorMinScore: description: Minimum similarity score (0-1) type: number webSearch: description: Web Search source configuration (when type === websearch) type: object properties: provider: description: 'Provider ID: tavily, brave, perplexity, exa, serpapi' type: string config: description: Web search provider configuration type: object properties: maxResults: type: integer searchDepth: type: string enum: - basic - advanced includeAnswer: type: boolean includeDomains: type: array items: type: string excludeDomains: type: array items: type: string pinnedUrls: type: array items: type: string additionalProperties: false allowUserPinnedUrlEdit: description: End users can add/remove pinned URLs type: boolean allowUserIncludeDomainEdit: description: End users can add/remove allowed domains type: boolean allowUserExcludeDomainEdit: description: End users can add/remove excluded domains type: boolean additionalProperties: false sharePointSite: description: Selected SharePoint site type: object additionalProperties: {} sharePointLibrary: description: Single library (legacy) nullable: true type: object additionalProperties: {} sharePointLibraries: description: Multiple libraries selection type: array items: type: object additionalProperties: {} sharePointIndexEntireSite: description: When true, index all libraries in the selected site type: boolean sharePointFolder: description: Subfolder within library for path filtering nullable: true type: object additionalProperties: {} required: - id - indexName additionalProperties: false title: DataSourceConfig description: >- Configuration for a single data source in the multi-source RAG pipeline deduplicateResults: description: Remove duplicate docs across sources type: boolean resultMergeStrategy: description: How to merge multi-source results type: string enum: - interleave - weighted - sequential allowUserSourceReorder: description: >- Chat-level: when false, end users cannot reorder sources in the runtime "use sources" drawer (UI-only affordance; default true) type: boolean sort: type: integer enableFeedback: type: boolean hideFilesAndCitationsFromUsers: description: When true, only admins/owners/contributors see files and citations type: boolean embeddedAgentMode: description: When true, shows only chat canvas without navigation elements type: boolean hidePromptsOnChatCanvas: description: When true, hides the prompt selector on the canvas type: boolean modelEndpoint: description: FK to AI model endpoint nullable: true type: string searchEndpoint: description: FK to AI Search endpoint nullable: true type: string defaultModel: type: string models: nullable: true type: array items: type: string searchLevel: nullable: true type: string enum: - basic - premium pageId: description: FK to Page for dynamic navigation type: string promptGroupId: description: FK to prompt group for curated prompt templates nullable: true type: string aiOptions: description: AI inference options — undefined means use system defaults type: object properties: maxTokens: type: integer topP: type: number temperature: type: number topNDocuments: type: integer vectorTopNDocuments: description: 'Number of documents for vector/hybrid search (default: 2000)' type: integer systemPrompt: type: string filter: type: string searchType: type: string enum: - simple - semantic - vector - vector_simple_hybrid - vector_semantic_hybrid semanticConfigurationName: type: string additionalProperties: false memoryEnabled: type: boolean memoryReadScopes: description: >- Scopes to read memories from (includes orgGlobal for admin-managed memories) type: array items: type: string enum: - userGlobal - userChat - orgGlobal - orgChat memoryWriteScope: description: Scope to write new memories to (excludes orgGlobal — admin only) type: string enum: - userGlobal - userChat - orgGlobal - orgChat autoStoreConversations: type: boolean memoryRetentionDays: type: integer memorySearchLimit: type: integer memoryTokenBudget: type: integer memoryTokenBudgetPercent: description: 'Max % of model context for memory (1-20%, default: 5%)' type: integer memoryRetrievalStrategy: type: string enum: - semantic - recency - hybrid - semantic_keyword - all preventUserDisableUserGlobalMemories: description: Lock User's Private Memories (USER_GLOBAL) — users cannot disable type: boolean preventUserDisableUserChatMemories: description: Lock User's Private Chat Memories (USER_CHAT) — users cannot disable type: boolean preventUserDisableOrgChatMemories: description: Lock This Chat's Shared Memories (ORG_CHAT) — users cannot disable type: boolean flowEngineFlowId: description: FK to FlowEngine flow type: string flowEngineEnabled: type: boolean promptForFlowVariables: description: Show entry prompt form on chat start to collect flow variables type: boolean prefilledFlowVariables: description: Pre-filled values for flow entry prompt variables type: object additionalProperties: {} lockedFlowVariables: description: Variable names that end users cannot override type: array items: type: string hiddenFlowVariables: description: Variable names hidden from end users at runtime type: array items: type: string autoSubmitLockedDefaults: description: When true and all variables are locked+filled, skip entry prompt type: boolean enabledMCPServers: description: Array of MCP server IDs enabled for this chat type: array items: type: string mcpServerConfigs: description: Per-chat config overrides for MCP servers type: object additionalProperties: {} isFeatured: description: Whether this chat is featured/promoted in the catalog type: boolean tags: type: array items: type: string defaultCompletionCriteria: description: >- ASSIGNMENT_COMPLETION_CRITERIA — default completion criteria for assignments type: string defaultMaxAttempts: type: integer defaultAllowDelegation: type: boolean defaultAllowRejection: type: boolean isWorkspace: description: >- Server-only: true when request targets the ephemeral cross-chat workspace. Never persisted. type: boolean required: - id - title additionalProperties: false title: Chat description: Chat tab configuration with multi-source RAG, ACL, and feature flags securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: Azure AD access token obtained via MSAL ````