openapi: 3.2.0 info: title: Pipeshub Agents API version: 1.0.0 contact: name: API Support email: support@pipeshub.com description: 'Operations tagged Agents across 2 of this provider''s published API definitions: pipeshub-openapi.yaml, pipeshub-openapi.yml. Each path carries the servers of the definition it was published in.' 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 security: - bearerAuth: [] - oauth2: [] tags: - name: Agents description: Custom AI agents with specialized capabilities and tool integrations paths: /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.' operationId: listAgents x-pipeshub-sdk: true 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 description: Case-insensitive search across agent name, description, and tags. Leading/trailing whitespace is trimmed; blank-after-trim values are rejected. - in: query name: sort_by required: false schema: type: string minLength: 1 maxLength: 100 default: updatedAtTimestamp description: Backend sort field. Leading/trailing whitespace is trimmed. 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 /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 x-pipeshub-sdk: true 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 '401': description: Unauthorized 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 /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.' operationId: getAgent x-pipeshub-sdk: true 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) or missing organization/user context on the authenticated request. ' 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. 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. **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 x-pipeshub-sdk: true 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: true 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: Forbidden — insufficient OAuth scope (`agent:write` required) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '400': description: 'Gateway validation failure. Returned for missing/invalid `agentKey`, empty `models` array, `models` without a reasoning entry, malformed JSON, and other Zod schema violations. Syntactically invalid JSON may also surface as `500` depending on the Express parser. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Agent not found or inaccessible. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Unexpected AI-backend or gateway failure. 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, and `GET /agents/{agentKey}` after delete return **HTTP 404** with an `ErrorResponse` body.' operationId: deleteAgent x-pipeshub-sdk: true 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' '401': description: Missing or invalid bearer token (e.g. `No token provided`) 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. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 /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 x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - agent:read parameters: - name: agentPage in: query required: false schema: type: integer minimum: 1 default: 1 - name: agentLimit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 5 responses: '200': description: Grouped archived conversations content: application/json: schema: $ref: '#/components/schemas/AgentArchivedGroupsResponse' '401': description: Unauthorized 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 /agents/{agentKey}/conversations/show/archives: get: tags: - Agents summary: List archived conversations for an agent description: Paginated list of archived conversations for the given agent key. operationId: listAgentConversationArchives x-pipeshub-sdk: true security: - bearerAuth: [] - oauth2: - agent:read parameters: - name: agentKey in: path required: true schema: type: string - name: page in: query schema: type: integer minimum: 1 default: 1 - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 20 - name: sortBy in: query schema: type: string enum: - createdAt - lastActivityAt - title - name: sortOrder in: query schema: type: string enum: - asc - desc - name: search in: query schema: type: string maxLength: 1000 - name: startDate in: query schema: type: string format: date-time - name: endDate in: query schema: type: string format: date-time responses: '200': description: Archived conversations for the agent content: application/json: schema: $ref: '#/components/schemas/AgentArchivedConversationListResponse' '400': description: Invalid query parameters (gateway validation) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized 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 /agents/{agentKey}/conversations/attachments/upload: post: tags: - Agents summary: Upload agent chat attachments description: 'Multipart upload of PDF, JPEG, or PNG files for agent chat. Same limits as assistant chat (`POST /conversations/attachments/upload`): up to 10 files, 5 MiB each. Proxies to the AI backend. Optional `conversationId` associates uploads with an existing agent thread.' operationId: uploadAgentConversationChatAttachments x-pipeshub-sdk: true 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`, no files, unsupported MIME type, or Multer rejection (e.g. file too large). ' '401': description: Unauthorized '403': description: Missing `agent:execute` scope '500': description: 'Gateway fallback when the upstream call does not return a status (implementation default). ' 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 /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 x-pipeshub-sdk: true 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 responses: '204': description: Success with no content (typical when upstream returns 204). '400': description: Invalid or blank path params (`agentKey` or `recordId`). content: application/json: schema: type: object additionalProperties: false required: - error properties: error: type: string example: recordId is required '401': description: Unauthorized '403': description: Missing `agent:execute` scope default: description: 'Other status codes are forwarded from the query service (e.g. 404) with an **empty** response body from this route. ' 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 /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 x-pipeshub-sdk: true 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) content: text/event-stream: schema: $ref: '#/components/schemas/AgentStreamSSEEvent' '400': description: Invalid request body '401': description: Unauthorized 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 /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 x-pipeshub-sdk: true 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) content: text/event-stream: schema: $ref: '#/components/schemas/AgentMessageStreamSSEEvent' '400': description: Invalid request body '401': description: Unauthorized '404': description: Conversation not found 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 /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: - `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 x-pipeshub-sdk: true 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.\n\nStable event names:\n- `RUN_FINISHED` — `{ type, result }`, where `result` contains the\n updated conversation and metadata\n- `RUN_ERROR` — `{ type, message, code? }`, reporting lookup,\n authorization, or regenerate-rule failures\n\nForwarded lifecycle and child-run events may include `runId`,\n`threadId`, and `parentRunId`. Additional backend-defined\nagent/tool events may be emitted.\nClients should ignore unknown event names.\n" 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. ' '401': description: Unauthorized 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 /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: false }` covers a `runId` that already finished or was never registered. `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 x-pipeshub-sdk: true 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 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 properties: cancelled: type: boolean '400': description: Missing or malformed `runId`. '401': description: Unauthorized '403': description: '`runId` exists but was registered under a different user, org, or conversation than this request.' '404': description: Conversation not found or unauthorized 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 /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 x-pipeshub-sdk: true 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. ' '401': description: Unauthorized '404': description: Conversation or message not found '500': description: Persistence layer failed to append the feedback entry. 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 /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 x-pipeshub-sdk: true 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. 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/AddMessageResponse' '400': description: 'Invalid request — `query` is missing or empty, 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. '403': description: Forbidden — the token lacks the `agent:execute` OAuth scope, or the caller cannot use this agent. '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, or the selected one could not start. 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 (AI service unreachable, timed out, returned no answer, or 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' 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 /agents/{agentKey}/conversations/{conversationId}/archive: post: tags: - Agents summary: Archive an agent conversation description: Marks the conversation as archived for the authenticated owner. operationId: archiveAgentConversation x-pipeshub-sdk: true 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: 'Invalid path input or the conversation is already archived. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 /agents/{agentKey}/conversations/{conversationId}/unarchive: post: tags: - Agents summary: Unarchive an agent conversation description: Restores an archived agent conversation to the active list. operationId: unarchiveAgentConversation x-pipeshub-sdk: true 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: 'Invalid path input or the conversation is not currently archived. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Conversation not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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 /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 controller trims the incoming title before saving it. A whitespace-only title can therefore still return HTTP 400 even if the raw string is non-empty.' operationId: updateAgentConversationTitle x-pipeshub-sdk: true 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' responses: '200': description: Title updated successfully content: application/json: schema: $ref: '#/components/schemas/AgentConversationTitleUpdateResponse' '400': description: 'Invalid path or body input. This includes Zod validation failures for malformed `conversationId` or invalid `title` payloads, plus controller-level bad requests such as titles that become empty after trimming. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized 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' 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 /agents/{agentKey}/conversations/{conversationId}/project: put: tags: - Agents summary: Link or unlink an agent conversation to a project description: 'Agent-conversation equivalent of `PUT /conversations/{conversationId}/project`. Set (`projectId: `) or clear (`projectId: null`) the project this agent conversation belongs to. Initiator-only; linking requires at least viewer access to the target project.' operationId: setAgentConversationProject x-pipeshub-sdk: true 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 content: application/json: schema: type: object additionalProperties: false required: - projectId properties: projectId: type: - string - 'null' format: objectId description: Target project id, or `null` to unlink. responses: '200': description: Agent conversation's project link updated content: application/json: schema: type: object additionalProperties: false required: - conversationId properties: conversationId: type: string format: objectId projectId: type: - string - 'null' format: objectId projectVisibility: type: - string - 'null' enum: - private - project '400': description: '`projectId` missing or not a valid ObjectId/`null`.' '401': description: Unauthorized '404': description: 'Agent conversation not found or caller is not the initiator, or the target project does not exist or is not visible to the caller. ' 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 /agents/{agentKey}/conversations/{conversationId}/project-visibility: patch: tags: - Agents summary: Override an agent conversation's project visibility description: 'Agent-conversation equivalent of `PATCH /conversations/{conversationId}/project-visibility`. Initiator-only; requires the conversation to already be linked to a project.' operationId: setAgentConversationProjectVisibility x-pipeshub-sdk: true 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 content: application/json: schema: type: object additionalProperties: false required: - visibility properties: visibility: type: string enum: - private - project responses: '200': description: Agent conversation's project visibility updated content: application/json: schema: type: object additionalProperties: false required: - conversationId - projectVisibility properties: conversationId: type: string format: objectId projectVisibility: type: string enum: - private - project '400': description: '`visibility` missing/invalid, or the conversation is not linked to a project. ' '401': description: Unauthorized '404': description: Agent conversation not found or caller is not the initiator. 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 /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`' operationId: deleteAgentConversationById x-pipeshub-sdk: true 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 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error while deleting the agent conversation 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 x-pipeshub-sdk: true 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 schema: type: string enum: - asc - desc default: desc - name: startDate in: query description: Filter messages created on or after this date schema: type: string format: date-time - name: endDate in: query description: Filter messages created on or before this date schema: type: string format: date-time - name: messageType in: query description: Filter messages by type 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' '401': description: Unauthorized '404': description: Conversation not found 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 /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 x-pipeshub-sdk: true 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. HTML/XSS payloads and format specifiers are rejected. ' schema: type: string maxLength: 1000 - name: startDate in: query description: 'Inclusive lower bound on `createdAt`. The handler accepts any JavaScript-parseable date string; invalid values return HTTP 400. ' schema: type: string example: '2026-05-26T00:00:00.000Z' - name: endDate in: query description: 'Inclusive upper bound on `createdAt`. The handler accepts any JavaScript-parseable date string; invalid values return HTTP 400. ' schema: type: string 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`. ' schema: type: string 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. ' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized 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 x-pipeshub-sdk: true 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. 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 — `query` is missing or empty, 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. '403': description: Forbidden — the token lacks the `agent:execute` OAuth scope, or the caller cannot use this agent. '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, or the selected one could not start. 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 (AI service unreachable, timed out, returned no answer, or 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' 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 components: schemas: 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 AgentConversationDetailAccess: type: object additionalProperties: false properties: isOwner: type: boolean accessLevel: type: string enum: - read - write AgentCreateToolsetName: type: string description: Registered toolset name (lowercase) accepted by the create-agent gateway. enum: - calendar - clickup - confluence - confluencedatacenter - drive - github - gmail - jira - jiradatacenter - lumos - mariadb - onedrive - outlook - redshift - salesforce - sharepoint - slack - teams - zoom 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 messages: type: array items: $ref: '#/components/schemas/Message' status: type: string enum: - None - Inprogress - Complete - Failed - Stopped description: Same values as `Conversation.status`. isShared: type: boolean sharedWith: type: array items: type: object properties: userId: type: string accessLevel: type: string enum: - read - write lastActivityAt: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time projectId: type: - string - 'null' format: objectId description: The project this agent conversation is linked to, if any. projectVisibility: type: - string - 'null' enum: - private - project description: 'Only meaningful when `projectId` is set. `project` exposes the conversation to every member of the linked project. ' 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. 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. 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' 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 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' 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 - 'null' items: $ref: '#/components/schemas/AgentCreateWarning' SemanticSearchHistoryFilters: type: object additionalProperties: false required: - applied - available properties: applied: $ref: '#/components/schemas/SemanticSearchHistoryFiltersApplied' available: $ref: '#/components/schemas/SemanticSearchHistoryFiltersAvailable' 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' AgentCreateResponseTool: type: object additionalProperties: false required: - name - fullName - key properties: name: type: string fullName: type: string key: type: string 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 AgentCreateWebSearch: description: 'Web-search attachment for an agent. Accepts a provider string, an object with at least a `provider` field, or `null`. ' anyOf: - type: - string - 'null' - type: object additionalProperties: false properties: provider: type: string providerKey: type: string maxLength: 256 providerLabel: type: string maxLength: 200 iconPath: type: string maxLength: 500 required: - provider 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' 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 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 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. ' 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 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. ' 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' runId: type: string format: uuid 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. ' 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 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. ' required: - id - createdAt - isShared - sharedWith - 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: userId: type: string format: objectId accessLevel: type: string enum: - read - write status: type: string enum: - None - Inprogress - Complete - Failed - Stopped failReason: type: string messages: type: array items: $ref: '#/components/schemas/AgentConversationDetailMessage' modelInfo: $ref: '#/components/schemas/ConversationModelInfo' pagination: $ref: '#/components/schemas/AgentConversationDetailPagination' access: $ref: '#/components/schemas/AgentConversationDetailAccess' 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' 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' 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. 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 - 'null' description: Short human-readable description of the agent. instructions: type: - string - 'null' 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. 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 - 'null' description: Greeting shown at conversation start. systemPrompt: type: - string - 'null' 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 - 'null' 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 - 'null' additionalProperties: false 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 - 'null' enum: - none - low - medium - high - max description: Agent-level reasoning effort used when a chat request omits its own. Null when unset. 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 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 AppliedFilterNode: type: object additionalProperties: false description: A single filter node selected by the user (used for display/persistence of active filters) 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 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' 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 - 'null' 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: 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). ' 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 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' Filters: type: object additionalProperties: false description: 'App connector instance ids and knowledge-base / record-group ids that narrow retrieval for a turn. For **org assistant** chat streams, send explicit `apps` / `kb` 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”). ' properties: apps: type: array items: type: string description: 'Connector instance ids to scope retrieval for this turn. Each element must be a valid UUID (connector app id, KB app id, record-group id, etc.). Gateway validation matches Zod `appOrKbIdSchema`. ' kb: type: array items: type: string description: 'Knowledge-base app ids to scope retrieval for this turn. Each element must be a valid UUID. ' 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 - 'null' category: type: - string - 'null' subcategory: type: - string - 'null' version: type: - string - 'null' status: type: - string - 'null' 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. 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 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: {} 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. 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 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_` For unhandled runtime errors (e.g. database unavailable) it is `INTERNAL_ERROR`. ' example: HTTP_BAD_REQUEST message: type: string description: Human-readable description of the error example: Admin access required metadata: type: object description: Additional context (only present in development environments) additionalProperties: true required: - error ConversationTitleUpdateRequest: type: object additionalProperties: false required: - title properties: title: type: string minLength: 1 maxLength: 200 description: New title for the conversation example: ABC News Follow-up 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 - 'null' enum: - null 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). 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' 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' 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: $ref: '#/components/schemas/AgentConversationDetailMessageCitation' confidence: type: - string - 'null' enum: - Very High - High - Medium - Low - Unknown 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: 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). ' 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 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. ' required: - chatMode AgentCreateRequest: type: object additionalProperties: false required: - name properties: name: type: string minLength: 1 maxLength: 200 description: Agent display name 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. When at least one model entry IS provided, the gateway requires at least one object entry with `isReasoning: true`. String-only arrays are schema-valid but rejected at runtime with HTTP 400 unless the array is empty. ' 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 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' webSearch: $ref: '#/components/schemas/AgentCreateWebSearch' defaultReasoningEffort: type: - string - 'null' enum: - none - low - medium - high - max description: Agent-level reasoning effort used when a chat request omits its own. 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. ' 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:\n- `None` — no activity yet\n- `Inprogress` — AI is processing\n- `Complete` — response ready\n- `Failed` — error occurred\n- `Stopped` — cancelled, or the client disconnected mid-answer;\n the last message keeps the partial answer\n" 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 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 description: Users this conversation is shared with isArchived: type: boolean default: false description: Whether this conversation is archived archivedBy: type: - string - 'null' format: objectId 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: 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 - 'null' format: objectId 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 - 'null' enum: - private - project 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' 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 uploaded file. 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. 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' 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. AgentRegenerateSSEEvent: type: object additionalProperties: false description: "SSE event envelope for `POST /agents/{agentKey}/conversations/{conversationId}/message/{messageId}/regenerate`.\nAG-UI is the sole wire protocol.\n\n`event` carries the AG-UI type name and `data` is a JSON object that\nincludes a `\"type\"` field matching `event`, plus type-specific\nfields. Stable gateway-generated top-level outcomes:\n\n- `RUN_FINISHED` returns `{ type, result }` where\n `result` is `{ conversation, recordsUsed, meta }` — the updated\n conversation plus request metadata after the regenerated response\n is persisted.\n- `RUN_ERROR` returns `{ type, message, code? }`. Conversation\n lookup failures, unauthorized conversation access, and regenerate\n rule failures such as \"not the last message\" are reported here.\n\nOther events are forwarded from the agent backend and should be\ntreated as informational updates. Those forwarded lifecycle and\nchild-run events may contain `runId`, `threadId`, and `parentRunId`;\nthe gateway-generated root terminal event does not.\n" 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`. ' 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`) AgentKnowledgeFiltersParsed: type: object additionalProperties: false description: 'Indexed scope for a knowledge connector: record-group ids and individual record ids. On GET, `filtersParsed` is this shape parsed from the stored `filters` JSON string. ' properties: recordGroups: type: array items: type: string description: 'Deprecated/legacy: record-group ids for connector record-group scoping (e.g. Confluence spaces, Jira projects). No longer set for KB (Collection) entries — a KB is identified by its own `connectorId`, not by an id in this list.' records: type: array items: type: string description: Individual record ids in scope. 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 - type: object additionalProperties: false required: - modelKey properties: modelKey: type: string minLength: 1 modelName: type: string provider: type: string isReasoning: type: boolean 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 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 AgentUpdateResponse: type: object additionalProperties: false required: - status - message properties: status: type: string enum: - success message: type: string example: Agent updated successfully 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 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 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. ' 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 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 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 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 MessageToolCall: type: object additionalProperties: false description: One tool invocation recorded on a message turn. properties: toolName: type: string toolResult: {} 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: userId: type: string format: objectId accessLevel: type: string enum: - read - write isArchived: type: boolean archivedBy: type: - string - 'null' format: objectId 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 - 'null' format: objectId conversationErrors: type: array items: type: object additionalProperties: false properties: 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. ' projectId: type: - string - 'null' format: objectId description: The project this agent conversation is linked to, if any. projectVisibility: type: - string - 'null' enum: - private - project description: 'Only meaningful when `projectId` is set. `project` exposes the conversation to every member of the linked project. ' 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 description: Admin-created toolset instance id instanceName: type: string description: Human-readable instance label (e.g. sidebar instance name) selectedTools: type: - array - 'null' 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. ' 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' 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`. ' properties: name: type: string minLength: 1 maxLength: 200 description: Agent display name 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. When a non-empty array is present, the Zod middleware requires at least one object entry with `isReasoning: true`. String-only arrays are schema-valid but rejected at runtime with HTTP 400 unless empty. ' 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 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' webSearch: $ref: '#/components/schemas/AgentCreateWebSearch' defaultReasoningEffort: type: - string - 'null' enum: - none - low - medium - high - max description: Agent-level reasoning effort used when a chat request omits its own. 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. ' 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 AgentCreateToolRef: type: object additionalProperties: false required: - name properties: name: type: string fullName: type: string description: type: string maxLength: 10000 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' AgentCreateToolset: type: object additionalProperties: false required: - name properties: name: $ref: '#/components/schemas/AgentCreateToolsetName' 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' 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' 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 - 'null' 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 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 - 'null' additionalProperties: false 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 - 'null' enum: - none - low - medium - high - max description: Agent-level reasoning effort used when a chat request omits its own. Null when unset. 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 - 'null' 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. 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 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 RegenerateRequest: type: object additionalProperties: false description: "Request body for regenerating an AI response. All fields are optional;\nwhen omitted the model selection and execution context from the\noriginal message are reused.\n\nSupported fields:\n- `filters` — optional `{ apps?, kb? }` filter object\n- `chatMode` — optional non-empty chat mode string\n- `modelKey`, `modelName`, `modelFriendlyName` —\n optional non-empty model override fields\n- `timezone` — optional non-empty client timezone string\n- `currentTime` — optional ISO 8601 / RFC 3339 datetime string with\n UTC `Z` or a numeric offset\n- `tools` — optional array of non-empty tool identifiers\n- `protocol` — optional inert compatibility field; when present it must\n be `agui`, which is also the protocol used when the field is omitted\n- `agentCapabilities` — optional per-request agent capability toggles\n" properties: filters: $ref: '#/components/schemas/Filters' 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 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 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. ' 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' runId: type: string format: uuid description: 'Client-generated identifier for this regeneration run. Send it here to enable `POST .../cancel {runId}` while it is still generating. ' 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' 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 AgentConversationTitleUpdateResponse: type: object additionalProperties: false required: - conversation - meta properties: conversation: $ref: '#/components/schemas/StoredAgentConversation' meta: $ref: '#/components/schemas/RequestMeta' 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. 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`. ' 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 - 'null' format: objectId isDeleted: type: boolean deletedBy: type: - string - 'null' format: objectId 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 AgentCreateWarning: type: object additionalProperties: false properties: name: type: string error: type: string 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 - 'null' applied: type: boolean 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' 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 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 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 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 - 'null' models: type: array items: type: string tags: type: array items: type: string webSearch: anyOf: - type: - object - 'null' additionalProperties: false properties: provider: type: string providerKey: type: string providerLabel: type: string defaultReasoningEffort: type: - string - 'null' enum: - none - low - medium - high - max description: Agent-level reasoning effort used when a chat request omits its own. Null when unset. sendUserContext: type: boolean description: When false, this agent omits user name/email/org from its system prompt. isActive: type: boolean isServiceAccount: type: boolean createdBy: type: string updatedBy: type: - string - 'null' 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' 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. AgentCreateKnowledge: type: object additionalProperties: false required: - connectorId properties: connectorId: type: string filters: oneOf: - $ref: '#/components/schemas/AgentKnowledgeFiltersParsed' - type: string - type: array items: {} 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 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 - 'null' end: type: - string - 'null' applied: type: boolean 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 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' AgentMessageStreamSSEEvent: type: object description: "Server-Sent Event envelope for `POST /agents/{agentKey}/conversations/{conversationId}/messages/stream`.\nAG-UI is the sole wire protocol.\n\n`event` carries the AG-UI type name and `data` is a JSON-encoded\nobject that includes a `\"type\"` field matching `event`, plus\ntype-specific fields. The public route requires `chatMode: quick`.\nForwarded lifecycle events may carry `runId`, `threadId`, and\n`parentRunId`. Stable gateway-generated top-level outcomes:\n\n- `CUSTOM` (`name: \"conversation_created\"`) — fired once after the\n SSE stream opens.\n- `RUN_FINISHED` — fired once after the upstream AI's result is\n parsed, citations are saved, and the updated conversation is\n persisted. The gateway emits `{ type, result }`; `result` carries\n `{ conversation, recordsUsed, meta }`.\n- `RUN_ERROR` — fired for runtime failures after the stream has\n already started, including conversation lookup failures, upstream\n AI startup failures, save failures, and stream transport errors.\n\nGateway-generated root terminal events do not contain `runId`,\n`threadId`, or `parentRunId`.\nClients should ignore unknown event names rather than treating them\nas errors.\n" 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`. ' 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. ' 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 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 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. ' 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. ' 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 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. ' 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' runId: type: string format: uuid 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. ' 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 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' 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' 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: $ref: '#/components/schemas/AppliedFilterNode' description: Applied app/connector filter nodes kb: type: array items: $ref: '#/components/schemas/AppliedFilterNode' description: Applied knowledge-base filter nodes 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 - 'null' extension: type: - string - 'null' webUrl: type: - string - 'null' previewRenderable: type: - boolean - 'null' hideWeburl: type: - boolean - 'null' connector: type: - string - 'null' connectorId: type: - string - 'null' 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. ' recordType: type: - string - 'null' blockNum: type: - array - 'null' items: type: - number - 'null' pageNum: type: - array - 'null' items: type: - number - 'null' sheetNum: type: - number - 'null' sheetName: type: - string - 'null' bounding_box: type: - array - 'null' items: $ref: '#/components/schemas/PersistedSemanticSearchBoundingBox' blockType: type: - string - 'null' description: 'Block type for this citation. Common values: `text`, `image`, `table_row`, `table`, `record_summary` (whole-record semantic summary chunk). ' blockText: type: - string - 'null' departments: type: - array - 'null' items: type: string languages: type: - array - 'null' items: type: string topics: type: - array - 'null' items: type: string 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 - 'null' 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' AgentCreateResponseMcpServerTool: type: object additionalProperties: false required: - name - fullName - key properties: name: type: string fullName: type: string key: type: string 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 OAuth app creator — 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 connector:read: Read connector configurations connector:write: Create and update connectors connector:sync: Trigger connector synchronization connector:delete: Delete connectors 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 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 connector:read: Read connector configurations connector:write: Create and update connectors connector:sync: Trigger connector synchronization connector:delete: Delete connectors config:read: Read system configuration config:write: Update system configuration crawl:read: Read crawling jobs crawl:write: Create and manage crawling jobs x-refined-from: - pipeshub-openapi.yaml - pipeshub-openapi.yml