openapi: 3.1.0 info: title: Nuwacom API description: API for Nuwacom application version: 1.0.0 servers: - url: https://{customer-tenant}.nuwacom.ai/ description: Nuwacom API components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: {} security: - bearerAuth: [] paths: /api/admin/space/create-space: post: responses: "200": description: Space was created successfully content: application/json: schema: type: object properties: spaceId: type: string description: The unique identifier of the newly created space. required: - spaceId operationId: postApiAdminSpaceCreate-space tags: - Workspaces parameters: [] summary: Create a Space description: Create a new nuwacom workspace in an organization. requestBody: content: application/json: schema: type: object properties: spaceId: type: string description: A unique identifier for the space. If not provided, a random ID will be generated.. title: type: string description: The human-readable space title that will appear throughout the workspace (e.g., "Customer Success" or "Sales"). organizationId: type: string description: The ID of the organization the space should be created in; Typically one organization for each instance and must already exist in the database. userId: type: string description: The ID of the user requesting space creation; used for permission checks and ownership. languages: type: array items: type: string description: 'A list of locale codes to be supported in the new space (e.g., "en-US", "de-DE"). Right now, we support the following languages: "en-US", "de-DE", "fr-FR".' required: - title - organizationId - userId - languages /api/ai/models: get: responses: "200": description: OK content: application/json: schema: type: array items: type: object properties: id: type: string description: Unique identifier of the LLM model. Used when referencing the model in API calls or UI selections and is generally a model id from the LLM provider. title: type: string description: Human-readable name shown to end users (e.g., "OpenAI o1 Preview" or "Mistral-large-2411"). vendor: enum: - OpenAI - Cohere - Mistral - Meta - Custom description: Vendor metadata describing who provides the underlying model (e.g., OpenAI, Anthropic, Mistral, Meta, Custom). hosting: enum: - EU - US - GLOBAL - Custom description: Indicates where the model is hosted (first-party, BYOK, region, etc.). Right now, we support "EU" and "US" regions. "Custom" is used for models that are hosted on a custom infrastructure. maxTokens: type: number description: Maximum number of tokens accepted per request for this model. maxOutputTokens: type: number description: Maximum number of tokens the model can generate in a single response. toolSupport: type: boolean description: Signals whether the model can call tools/functions during execution. modelType: anyOf: - enum: - o1 - o3 nullable: true description: Optional model family classification. Null when the model does not belong to a specific OpenAI o-series. visionSupport: type: boolean description: True if the model understands image inputs alongside text. apiVersion: enum: - v1 - v2 description: Version of the API/SDK required to access this model. canvasSupport: type: boolean description: Indicates whether the model supports canvas-style collaborative generation features. enabled: type: boolean description: Optional flag to hide or disable the model without removing its metadata. Defaults to true. required: - id - title - vendor - hosting - maxTokens - maxOutputTokens - toolSupport - visionSupport - apiVersion - canvasSupport operationId: getApiAiModels tags: - AI parameters: [] summary: List all AI models description: List all supported AI models /api/ai/models/{spaceId}: get: responses: "200": description: OK content: application/json: schema: type: array items: type: object properties: id: type: string description: Unique identifier of the LLM model. Used when referencing the model in API calls or UI selections and is generally a model id from the LLM provider. title: type: string description: Human-readable name shown to end users (e.g., "OpenAI o1 Preview" or "Mistral-large-2411"). vendor: enum: - OpenAI - Cohere - Mistral - Meta - Custom description: Vendor metadata describing who provides the underlying model (e.g., OpenAI, Anthropic, Mistral, Meta, Custom). hosting: enum: - EU - US - GLOBAL - Custom description: Indicates where the model is hosted (first-party, BYOK, region, etc.). Right now, we support "EU" and "US" regions. "Custom" is used for models that are hosted on a custom infrastructure. maxTokens: type: number description: Maximum number of tokens accepted per request for this model. maxOutputTokens: type: number description: Maximum number of tokens the model can generate in a single response. toolSupport: type: boolean description: Signals whether the model can call tools/functions during execution. modelType: anyOf: - enum: - o1 - o3 nullable: true description: Optional model family classification. Null when the model does not belong to a specific OpenAI o-series. visionSupport: type: boolean description: True if the model understands image inputs alongside text. apiVersion: enum: - v1 - v2 description: Version of the API/SDK required to access this model. canvasSupport: type: boolean description: Indicates whether the model supports canvas-style collaborative generation features. enabled: type: boolean description: Optional flag to hide or disable the model without removing its metadata. Defaults to true. required: - id - title - vendor - hosting - maxTokens - maxOutputTokens - toolSupport - visionSupport - apiVersion - canvasSupport operationId: getApiAiModelsBySpaceId tags: - AI parameters: - name: spaceId in: path required: true description: Unique ID of the space to return available AI models for. schema: kind: schema type: string expects: string async: false ~standard: version: 1 vendor: valibot summary: List space AI models description: List all supported AI models for a specific space /api/ai/generate/prompt: {} /api/auth/api_key/create: post: responses: "200": description: API key created successfully content: application/json: schema: type: object properties: id: type: string description: Unique ID of the newly created API key. key: type: string description: The API secret itself. This is confidential and should be stored securely. required: - id - key "400": description: Invalid request data "401": description: Unauthorized operationId: postApiAuthApi_keyCreate tags: - Auth parameters: [] summary: Create an API key description: Creates a new API key for the authenticated user with specified permissions and optional expiration. requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Name for the API key (e.g., "Zapier integration"). permissions: type: object additionalProperties: type: array items: type: string description: A map of space IDs to permissions. Each space ID is associated with an array of permissions that the API key will have access to in that space. expiration: anyOf: - type: string - type: number description: Optional expiration value (ISO timestamp or UNIX seconds) after which the API key becomes invalid. required: - name - permissions /api/hubspot/create-contact: {} /api/kb/assets: post: responses: "201": description: Asset created successfully content: application/json: schema: type: object properties: id: type: string format: uuid required: - id "400": description: Bad request, invalid input operationId: postApiKbAssets tags: - Assets parameters: [] summary: Add an asset via URL description: Add an asset to the system by providing a URL to the asset requestBody: content: application/json: schema: type: object properties: spaceId: anyOf: - type: string minLength: 2 maxLength: 6 - type: string minLength: 21 maxLength: 21 description: Unique ID of the space the asset should be added to. connectorId: type: number description: Identifier of the connector (e.g., SharePoint, Google Drive) the asset belongs to. metadata: type: object additionalProperties: {} description: JSON metadata string that will be stored alongside the asset (e.g., author, custom tags). path: type: array items: type: string description: Hierarchical path (array of folder names) describing where the asset lives in the connector. fetchAuth: anyOf: - type: object properties: type: enum: - basic username: type: string password: type: string required: - type - username - password - type: object properties: type: enum: - bearer token: type: string required: - type - token mimeType: type: string description: MIME type of the remote asset (e.g., "application/pdf", "text/plain"). name: type: string description: Optional display name for the asset. Defaults to the filename if omitted. url: type: string format: uri description: Reachable URL that the backend should fetch and ingest (can be signed or public). required: - spaceId - mimeType - url /api/kb/assets/upload: post: responses: "200": description: Asset already exists content: application/json: schema: type: object properties: id: type: string format: uuid required: - id "201": description: Asset uploaded successfully content: application/json: schema: type: object properties: id: type: string format: uuid required: - id operationId: postApiKbAssetsUpload tags: - Assets parameters: [] summary: Upload an asset description: Upload an asset to the system requestBody: content: multipart/form-data: schema: type: object properties: spaceId: anyOf: - type: string minLength: 2 maxLength: 6 - type: string minLength: 21 maxLength: 21 description: Unique ID of the space the asset should be added to. connectorId: type: number description: Identifier of the connector (e.g., SharePoint, Google Drive) the asset belongs to. metadata: type: object additionalProperties: {} description: JSON metadata string that will be stored alongside the asset (e.g., author, custom tags). path: type: array items: type: string description: Hierarchical path (array of folder names) describing where the asset lives in the connector. file: description: The file to upload. This contains the name, MIME type, and data. required: - spaceId - file /api/kb/assets/{spaceId}/{assetId}: get: responses: "200": description: Asset payload returned successfully. "403": description: Returned when the caller lacks permission to view assets in this space. "404": description: Returned when the asset does not exist in the provided space. operationId: getApiKbAssetsBySpaceIdByAssetId tags: - Assets parameters: - in: path name: spaceId schema: anyOf: - type: string minLength: 2 maxLength: 6 - type: string minLength: 21 maxLength: 21 description: Space identifier for the asset you are trying to read, update, or delete. required: true - in: path name: assetId schema: type: string format: uuid description: The asset UUID that uniquely identifies the record within the database. required: true summary: Get an asset description: Return the complete asset record (name, MIME type, connector info, metadata, processing state, etc.) for the provided asset as long as the caller has read access to the space. patch: responses: "204": description: Asset metadata updated successfully. "403": description: Returned when the caller cannot update assets in this space. "404": description: Asset not found or belongs to another space. operationId: patchApiKbAssetsBySpaceIdByAssetId tags: - Assets parameters: - in: path name: spaceId schema: anyOf: - type: string minLength: 2 maxLength: 6 - type: string minLength: 21 maxLength: 21 description: Space identifier for the asset you are trying to read, update, or delete. required: true - in: path name: assetId schema: type: string format: uuid description: The asset UUID that uniquely identifies the record within the database. required: true summary: Update an asset description: Update mutable asset metadata (name, connector assignment, metadata JSON, file path info, etc.) without re-uploading the file itself. requestBody: content: application/json: schema: type: object properties: connectorId: type: number description: Identifier of the connector (e.g., SharePoint, Google Drive) the asset belongs to. metadata: type: object additionalProperties: {} description: JSON metadata string that will be stored alongside the asset (e.g., author, custom tags). path: type: array items: type: string description: Hierarchical path (array of folder names) describing where the asset lives in the connector. fetchAuth: anyOf: - type: object properties: type: enum: - basic username: type: string password: type: string required: - type - username - password - type: object properties: type: enum: - bearer token: type: string required: - type - token mimeType: type: string description: MIME type of the remote asset (e.g., "application/pdf", "text/plain"). name: type: string description: Optional display name for the asset. Defaults to the filename if omitted. required: [] description: Payload for updating existing assets. Only include the fields that need to change—leave everything else out. delete: responses: "204": description: Asset deleted successfully. "403": description: Returned when the caller does not have delete permissions for the asset or space. "404": description: Returned when the asset cannot be found in the specified space. operationId: deleteApiKbAssetsBySpaceIdByAssetId tags: - Assets parameters: - in: path name: spaceId schema: anyOf: - type: string minLength: 2 maxLength: 6 - type: string minLength: 21 maxLength: 21 description: Space identifier for the asset you are trying to read, update, or delete. required: true - in: path name: assetId schema: type: string format: uuid description: The asset UUID that uniquely identifies the record within the database. required: true summary: Delete an asset description: Permanently delete an asset from the given space. This removes the stored file and any derived embeddings for that asset. /api/subscription/create-checkout-session: {} /api/subscription/create-portal-session: {} /api/subscription/plans: {} /api/subscription/status/{organizationId}: {} /api/subscription/paid-seats-left/{organizationId}: {} /api/embed/chat/{chatId}: get: responses: "200": description: OK content: application/json: schema: type: object properties: agent: type: object properties: id: type: string description: Agent UUID used to load the bot’s full profile (name, system prompt, data sources) when the embed initializes. required: - id settings: type: object properties: id: type: string description: Settings UUID that points to the saved embed configuration (colors, behavior toggles, etc.). $avatar: anyOf: - type: string nullable: true required: - id required: - agent - settings operationId: getApiEmbedChatByChatId tags: - Embedded Chat parameters: - in: path name: chatId schema: type: string description: The specific embedded chat identifier (UUID or unique string) used to retrieve the chat settings and agent information for the embedded chat experience. This value is found in the embed URL (e.g., /embed/chat/{chatId}). required: true summary: Get chat by ID description: Get the chat settings and agent information by chat ID /api/embed/chat/{agentId}/avatar: get: responses: "200": description: Image data operationId: getApiEmbedChatByAgentIdAvatar tags: - Embedded Chat parameters: - in: path name: agentId schema: type: string description: Unique ID of the agent to retrieve the avatar for. This value is found in the embed URL (e.g., /embed/chat/{agentId}). required: true summary: Get agent avatar description: Get the avatar of the agent by its ID /v1/openai/chat/completions: post: responses: "200": description: Successful completion response (see [OpenAI Completions Object](https://platform.openai.com/docs/api-reference/completions/object)) operationId: postV1OpenaiChatCompletions tags: - Completion API parameters: [] summary: OpenAI Chat Completion description: Create a new AI completion. You can find the supported models using [List all AI models](/api-reference/ai/list-all-ai-models). requestBody: content: application/json: schema: type: object properties: model: anyOf: - type: string nullable: true description: Use this in the API call to specify the model to use for the completion request. Is generally the model ID from the LLM provider (e.g., "gpt-4o", "o1"). temperature: type: number description: Sampling temperature. Higher values make responses more adventurous; lower values keep them conservative. top_p: type: number description: Nucleus sampling parameter. Use this instead of temperature when you want to strictly cap how much of the probability mass is considered. agentId: anyOf: - type: string format: uuid nullable: true description: "Unique ID of the agent to use for the completion request. Used to load the agent's full configuration (system prompt, knowledge sources, etc.). NB: Agent must already be created in the database and available for the space." voiceId: anyOf: - type: string format: uuid nullable: true description: "UUID of the Voice to use for the completion request. NB: Voice must already be created in the database and available for the space." taskId: anyOf: - type: string format: uuid nullable: true description: "ID of the Task to use for the completion request. Used to tie the completion back to a workflow step or scheduled job. NB: Task must already be created in the database and available for the space." capabilities: type: object properties: webSearch: type: boolean knowledgeBaseSearch: type: boolean visionEnabled: type: boolean required: [] description: Provide an object of capabilities to enable the LLM perform specific tasks better (e.g., web search, internal KB, canvas, etc.). attachmentIds: type: array items: type: string format: uuid description: Array of asset IDs (files, snippets, etc.) that should be injected into the completion request as supporting context. contentIds: type: array items: type: string format: uuid description: Array of Content document IDs to include in the RAG context. Used to pass relevant document IDs so their content is included as additional background information for the completion request. folderIds: type: array items: type: string format: uuid description: Array of Folder IDs to include in the RAG context. When provided, the LLM will use assets/documents within these folders as additional background information for the completion request. messages: type: array items: type: object properties: role: enum: - assistant - user - system content: anyOf: - type: string - type: array items: anyOf: - type: object properties: type: enum: - text text: type: string required: - type - text - type: object properties: type: enum: - image kbAssetId: type: string format: uuid required: - type - kbAssetId required: - role - content minItems: 1 description: Ordered chat messages that make up the conversation history. Always include the user’s latest turn; prepend prior turns when you want additional context. stream: type: boolean description: When true the API sends partial chunks as the model generates them (ideal for typing indicators). Set to false to receive a single response payload. parent_message_id: anyOf: - type: number nullable: true description: Internal reference to the last assistant message in the thread. Include this when you need the completion to “continue” an earlier answer. conversation_id: anyOf: - type: string format: uuid nullable: true description: Conversation UUID tying multiple completions together. Provide it to append to an existing thread; leave empty to start fresh. space_id: type: string format: uuid required: - messages - space_id externalDocs: description: OpenAI API documentation for chat completions url: https://platform.openai.com/docs/api-reference/chat/create