openapi: 3.0.0 info: description: Unified API for QuantCDN Admin and QuantCloud Platform services title: QuantCDN AI Agents API version: 4.15.8 servers: - description: QuantCDN Public Cloud url: https://dashboard.quantcdn.io - description: QuantGov Cloud url: https://dash.quantgov.cloud security: - BearerAuth: [] tags: - description: Pre-configured AI assistants with specific system prompts, model settings, and tool permissions name: AI Agents paths: /api/v3/organizations/{organisation}/ai/agents: get: description: "Lists all AI agents for an organization. Agents are pre-configured AI assistants with specific system prompts, model settings, and tool permissions.\n *\n * **Features:**\n * - Filter by group (e.g., 'development', 'compliance')\n * - Organization-scoped\n * - Returns agent configurations without execution history" operationId: listAIAgents parameters: - description: The organisation ID explode: false in: path name: organisation required: true schema: type: string style: simple - description: Optional group filter (e.g., 'development', 'compliance') explode: true in: query name: group required: false schema: type: string style: form responses: '200': content: application/json: schema: $ref: '#/components/schemas/listAIAgents_200_response' description: List of agents retrieved successfully '403': description: Access denied '500': description: Failed to retrieve agents summary: List AI Agents tags: - AI Agents post: description: "Creates a new AI agent with specific configuration, system prompt, and tool permissions.\n *\n * **Agent Configuration:**\n * - **System Prompt**: Instructions that guide the agent's behavior\n * - **Model**: Which foundation model to use (e.g., 'amazon.nova-pro-v1:0')\n * - **Temperature**: Creativity level (0-1)\n * - **Allowed Tools**: Which tools the agent can auto-execute\n * - **Allowed Collections**: Vector DB collections for RAG\n * - **Group**: Optional categorization (e.g., 'development', 'compliance')\n *\n * **Auto-Execution:**\n * All tools are automatically executed when an agent requests them (no client confirmation needed)." operationId: createAIAgent parameters: - description: The organisation ID explode: false in: path name: organisation required: true schema: type: string style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/createAIAgent_request' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/createAIAgent_201_response' description: Agent created successfully '400': description: Invalid request parameters '403': description: Access denied '500': description: Failed to create agent summary: Create AI Agent tags: - AI Agents /api/v3/organizations/{organisation}/ai/agents/{agentId}: delete: description: Permanently deletes an AI agent. This action cannot be undone. operationId: deleteAIAgent parameters: - description: The organisation ID explode: false in: path name: organisation required: true schema: type: string style: simple - description: The agent ID explode: false in: path name: agentId required: true schema: format: uuid type: string style: simple responses: '200': content: application/json: schema: $ref: '#/components/schemas/deleteAIAgent_200_response' description: Agent deleted successfully '403': description: Access denied '404': description: Agent not found '500': description: Failed to delete agent summary: Delete Agent tags: - AI Agents get: description: Retrieves detailed configuration for a specific AI agent. operationId: getAIAgent parameters: - description: The organisation ID explode: false in: path name: organisation required: true schema: type: string style: simple - description: The agent ID explode: false in: path name: agentId required: true schema: format: uuid type: string style: simple responses: '200': content: application/json: schema: $ref: '#/components/schemas/getAIAgent_200_response' description: Agent details retrieved successfully '403': description: Access denied '404': description: Agent not found '500': description: Failed to retrieve agent summary: Get Agent Details tags: - AI Agents put: description: Updates an existing AI agent configuration. All fields except agentId, organizationId, createdAt, and createdBy can be updated. operationId: updateAIAgent parameters: - description: The organisation ID explode: false in: path name: organisation required: true schema: type: string style: simple - description: The agent ID explode: false in: path name: agentId required: true schema: format: uuid type: string style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/updateAIAgent_request' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/updateAIAgent_200_response' description: Agent updated successfully '400': description: Invalid request parameters '403': description: Access denied '404': description: Agent not found '500': description: Failed to update agent summary: Update Agent tags: - AI Agents /api/v3/organizations/{organisation}/ai/agents/{agentId}/chat: post: description: "Initiates a chat session with a specific AI agent. The agent's configuration (system prompt, temperature, model, allowed tools) is automatically applied.\n *\n * **Key Features:**\n * - **Session Management**: Automatic session creation and state tracking\n * - **Multi-turn Conversations**: Full conversation history maintained server-side\n * - Agent's system prompt is prepended to conversation\n * - Only agent's allowed tools are available\n * - All tools are auto-executed on cloud (no client confirmation needed)\n * - Temperature and model from agent config\n * - Supports sync, streaming, and async modes\n *\n * **Execution Modes:**\n * - **Sync Mode** (default): Standard JSON response, waits for completion\n * - **Streaming Mode**: Set `stream: true` for SSE token-by-token responses\n * - **Async Mode**: Set `async: true` for long-running tasks with polling\n *\n * **Async/Durable Mode (`async: true`):**\n * - Returns immediately with `requestId` and `pollUrl` (HTTP 202)\n * - Uses AWS Lambda Durable Functions for long-running agent tasks\n * - All tools are auto-executed on cloud (no `waiting_callback` state)\n * - Poll `/ai/chat/executions/{requestId}` for status\n * - Ideal for agents with slow tools (image generation, web search, etc.)\n *\n * **Session Support:**\n * - Omit `sessionId` to create a new session automatically\n * - Include `sessionId` to continue an existing conversation\n * - Sessions expire after 60 minutes of inactivity\n * - Sessions work in all modes (sync, streaming, async)\n * - Use `/sessions/{sessionId}` to retrieve full conversation history" operationId: chatWithAIAgent parameters: - description: The organisation ID explode: false in: path name: organisation required: true schema: type: string style: simple - description: The agent ID explode: false in: path name: agentId required: true schema: format: uuid type: string style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/chatWithAIAgent_request' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/chatWithAIAgent_200_response' description: Agent response generated successfully (sync mode) '202': content: application/json: schema: $ref: '#/components/schemas/chatWithAIAgent_202_response' description: 'Async execution started (when `async: true` in request)' '400': description: Invalid request parameters '403': description: Access denied '404': description: Agent not found '500': description: Failed to chat with agent summary: Chat with AI Agent tags: - AI Agents /api/v3/organizations/{organisation}/ai/agents/{agentId}/overlay: delete: description: Removes the per-organisation overlay for a global agent, reverting it to platform defaults. operationId: deleteAgentOverlay parameters: - description: The organisation ID explode: false in: path name: organisation required: true schema: type: string style: simple - description: Global agent identifier explode: false in: path name: agentId required: true schema: type: string style: simple responses: '200': content: application/json: schema: $ref: '#/components/schemas/deleteAgentOverlay_200_response' description: Overlay deleted — agent reverted to defaults '403': description: Access denied '404': description: Not a global agent '500': description: Failed to reset overlay summary: Delete Agent Overlay tags: - AI Agents get: description: 'Returns the per-organisation overlay for a global agent, plus base agent metadata for UI context. If no overlay exists the response contains `overlay: null`. Overlays can only be created for global agents.' operationId: getAgentOverlay parameters: - description: The organisation ID explode: false in: path name: organisation required: true schema: type: string style: simple - description: Global agent identifier (e.g., 'quantgov-code') explode: false in: path name: agentId required: true schema: type: string style: simple responses: '200': content: application/json: schema: $ref: '#/components/schemas/getAgentOverlay_200_response' description: Overlay retrieved (may be null if none set) '403': description: Access denied '404': description: Not a global agent '500': description: Failed to retrieve overlay summary: Get Agent Overlay tags: - AI Agents put: description: Creates or replaces the per-organisation overlay for a global agent. PUT is full replacement — omitted optional fields are removed. Include `version` from a prior GET to enable compare-and-swap (409 on conflict). Omit for last-writer-wins. operationId: upsertAgentOverlay parameters: - description: The organisation ID explode: false in: path name: organisation required: true schema: type: string style: simple - description: Global agent identifier explode: false in: path name: agentId required: true schema: type: string style: simple requestBody: content: application/json: schema: $ref: '#/components/schemas/upsertAgentOverlay_request' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/upsertAgentOverlay_200_response' description: Overlay created or updated '400': description: Invalid request parameters '403': description: Access denied '404': description: Not a global agent '409': description: Version conflict — overlay was modified concurrently '500': description: Failed to save overlay summary: Upsert Agent Overlay tags: - AI Agents components: schemas: chatWithAIAgent_200_response: example: response: stopReason: stopReason usage: costCents: 5.962134 inputTokens: 0 outputTokens: 6 totalTokens: 1 toolResults: - '{}' - '{}' text: text sessionId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 properties: sessionId: format: uuid type: string response: $ref: '#/components/schemas/chatWithAIAgent_200_response_response' type: object chatWithAIAgent_200_response_response: example: stopReason: stopReason usage: costCents: 5.962134 inputTokens: 0 outputTokens: 6 totalTokens: 1 toolResults: - '{}' - '{}' text: text properties: text: type: string stopReason: type: string usage: $ref: '#/components/schemas/chatWithAIAgent_200_response_response_usage' toolResults: items: type: object type: array type: object deleteAIAgent_200_response: example: success: true message: Agent deleted successfully properties: success: example: true type: boolean message: example: Agent deleted successfully type: string type: object createAIAgent_201_response: example: agent: '{}' success: true message: Agent created successfully properties: success: example: true type: boolean agent: type: object message: example: Agent created successfully type: string type: object upsertAgentOverlay_200_response: example: overlay: '{}' properties: overlay: type: object type: object getAgentOverlay_200_response_base: description: Base global agent metadata example: assignedSkillIds: - assignedSkillIds - assignedSkillIds agentId: agentId modelId: modelId name: name allowedTools: - allowedTools - allowedTools properties: agentId: type: string name: type: string modelId: type: string allowedTools: items: type: string type: array assignedSkillIds: items: type: string type: array type: object chatWithAIAgent_200_response_response_usage: example: costCents: 5.962134 inputTokens: 0 outputTokens: 6 totalTokens: 1 properties: inputTokens: type: integer outputTokens: type: integer totalTokens: type: integer costCents: description: Cost of this inference call in US cents format: float type: number type: object updateAIAgent_request: properties: name: type: string description: type: string group: type: string systemPrompt: type: string temperature: maximum: 1 minimum: 0 type: number modelId: type: string maxTokens: maximum: 200000 minimum: 1 type: integer allowedTools: items: type: string type: array allowedCollections: items: type: string type: array assignedSkills: description: Skill IDs to assign to this agent items: type: string type: array longContext: description: Enable 1M context window support type: boolean guardrailPreset: description: Guardrail preset name enum: - official - official-sensitive - protected type: string filterPolicies: description: Filter policy IDs to apply to this agent's inference requests items: type: string type: array type: object getAIAgent_200_response: example: agent: assignedSkills: - assignedSkills - assignedSkills agentId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 guardrailPreset: guardrailPreset modelId: modelId description: description hasOverlay: true systemPrompt: systemPrompt createdAt: 2000-01-23 04:56:07+00:00 createdBy: createdBy longContext: true name: name temperature: 0.8008281904610115 maxTokens: 6 allowedCollections: - allowedCollections - allowedCollections isGlobal: true group: group allowedTools: - allowedTools - allowedTools updatedAt: 2000-01-23 04:56:07+00:00 properties: agent: $ref: '#/components/schemas/getAIAgent_200_response_agent' type: object listAIAgents_200_response: example: agents: - assignedSkills: - assignedSkills - assignedSkills agentId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 guardrailPreset: guardrailPreset modelId: modelId description: description hasOverlay: true createdAt: 2000-01-23 04:56:07+00:00 longContext: true name: name temperature: 0.8008281904610115 maxTokens: 6 isGlobal: true group: group allowedTools: - allowedTools - allowedTools updatedAt: 2000-01-23 04:56:07+00:00 - assignedSkills: - assignedSkills - assignedSkills agentId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 guardrailPreset: guardrailPreset modelId: modelId description: description hasOverlay: true createdAt: 2000-01-23 04:56:07+00:00 longContext: true name: name temperature: 0.8008281904610115 maxTokens: 6 isGlobal: true group: group allowedTools: - allowedTools - allowedTools updatedAt: 2000-01-23 04:56:07+00:00 properties: agents: items: $ref: '#/components/schemas/listAIAgents_200_response_agents_inner' type: array type: object getAgentOverlay_200_response: example: overlay: disabledSkills: - disabledSkills - disabledSkills guardrailPreset: guardrailPreset modelId: modelId disabledTools: - disabledTools - disabledTools temperature: 0.8008281904610115 maxTokens: 6 additionalSkills: - additionalSkills - additionalSkills allowedCollections: - allowedCollections - allowedCollections systemPromptAppend: systemPromptAppend version: 1 additionalTools: - additionalTools - additionalTools base: assignedSkillIds: - assignedSkillIds - assignedSkillIds agentId: agentId modelId: modelId name: name allowedTools: - allowedTools - allowedTools properties: overlay: $ref: '#/components/schemas/getAgentOverlay_200_response_overlay' base: $ref: '#/components/schemas/getAgentOverlay_200_response_base' type: object getAgentOverlay_200_response_overlay: example: disabledSkills: - disabledSkills - disabledSkills guardrailPreset: guardrailPreset modelId: modelId disabledTools: - disabledTools - disabledTools temperature: 0.8008281904610115 maxTokens: 6 additionalSkills: - additionalSkills - additionalSkills allowedCollections: - allowedCollections - allowedCollections systemPromptAppend: systemPromptAppend version: 1 additionalTools: - additionalTools - additionalTools nullable: true properties: modelId: type: string temperature: type: number maxTokens: type: integer disabledSkills: items: type: string type: array additionalSkills: items: type: string type: array additionalTools: items: type: string type: array disabledTools: items: type: string type: array systemPromptAppend: type: string allowedCollections: items: type: string type: array guardrailPreset: type: string version: type: integer type: object updateAIAgent_200_response: example: agent: '{}' success: true message: Agent updated successfully properties: success: example: true type: boolean agent: type: object message: example: Agent updated successfully type: string type: object deleteAgentOverlay_200_response: example: success: true message: Agent reverted to defaults properties: success: example: true type: boolean message: example: Agent reverted to defaults type: string type: object chatWithAIAgent_202_response: example: agentId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 requestId: 90fe0c53-a41b-4b28-b19e-5e900b3df959 pollUrl: /ai/chat/executions/90fe0c53-a41b-4b28-b19e-5e900b3df959 agentName: Weather Assistant sessionId: sessionId message: Agent execution started. Poll the status endpoint for updates. status: queued properties: requestId: description: Unique request identifier for polling example: 90fe0c53-a41b-4b28-b19e-5e900b3df959 type: string agentId: description: The agent processing the request format: uuid type: string agentName: description: Human-readable agent name example: Weather Assistant type: string sessionId: description: Session ID (if provided) type: string status: description: Initial status enum: - queued example: queued type: string message: example: Agent execution started. Poll the status endpoint for updates. type: string pollUrl: description: URL to poll for execution status example: /ai/chat/executions/90fe0c53-a41b-4b28-b19e-5e900b3df959 type: string required: - agentId - pollUrl - requestId - status type: object getAIAgent_200_response_agent: example: assignedSkills: - assignedSkills - assignedSkills agentId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 guardrailPreset: guardrailPreset modelId: modelId description: description hasOverlay: true systemPrompt: systemPrompt createdAt: 2000-01-23 04:56:07+00:00 createdBy: createdBy longContext: true name: name temperature: 0.8008281904610115 maxTokens: 6 allowedCollections: - allowedCollections - allowedCollections isGlobal: true group: group allowedTools: - allowedTools - allowedTools updatedAt: 2000-01-23 04:56:07+00:00 properties: agentId: format: uuid type: string name: type: string description: type: string group: type: string systemPrompt: type: string modelId: type: string temperature: type: number maxTokens: type: integer allowedTools: items: type: string type: array allowedCollections: items: type: string type: array assignedSkills: items: type: string type: array longContext: description: Whether 1M context window is enabled type: boolean guardrailPreset: description: Guardrail preset name type: string isGlobal: description: Whether this is a platform-managed global agent type: boolean hasOverlay: description: Whether the requesting org has a per-org overlay for this global agent type: boolean createdBy: type: string createdAt: format: date-time type: string updatedAt: format: date-time type: string type: object createAIAgent_request: properties: name: example: Code Review Assistant type: string description: example: Reviews code for security vulnerabilities and best practices type: string group: example: development type: string systemPrompt: example: You are a senior software engineer specializing in secure code review. type: string temperature: example: 0.3 maximum: 1 minimum: 0 type: number modelId: example: anthropic.claude-3-5-sonnet-20241022-v2:0 type: string maxTokens: example: 4000 maximum: 200000 minimum: 1 type: integer allowedTools: example: - fetch_web_content - search_web items: type: string type: array allowedCollections: items: type: string type: array assignedSkills: description: Skill IDs to assign to this agent items: type: string type: array createdBy: description: User identifier who created the agent type: string longContext: description: Enable 1M context window support type: boolean guardrailPreset: description: Guardrail preset name enum: - official - official-sensitive - protected type: string filterPolicies: description: Filter policy IDs to apply to this agent's inference requests items: type: string type: array required: - description - modelId - name - systemPrompt type: object chatWithAIAgent_request: properties: message: description: The user's message to the agent type: string sessionId: description: Optional session ID to continue a conversation format: uuid type: string userId: description: Optional user identifier for session isolation type: string stream: default: false description: Whether to stream the response (SSE) type: boolean async: default: false description: Enable async/durable execution mode. When true, returns 202 with pollUrl. Use for long-running agent tasks. type: boolean system: description: Optional additional system prompt (appended to agent's configured prompt) type: string longContext: default: false description: Per-request override to force 1M context window routing type: boolean maxToolIterations: description: Maximum tool auto-execution iterations for this request maximum: 1000 minimum: 1 type: integer allowedCollections: description: Per-request override for vector DB collections the agent can query items: type: string type: array required: - message type: object upsertAgentOverlay_request: properties: modelId: description: Override the base agent's model type: string temperature: description: Override temperature maximum: 1 minimum: 0 type: number maxTokens: description: Override max tokens minimum: 1 type: integer disabledSkills: description: Global skill IDs to exclude items: type: string type: array additionalSkills: description: Org-owned skill IDs to add items: type: string type: array additionalTools: description: Tool names to add items: type: string type: array disabledTools: description: Tool names to remove items: type: string type: array systemPromptAppend: description: Text appended to base system prompt type: string allowedCollections: description: Vector DB collections items: type: string type: array guardrailPreset: description: Guardrail preset enum: - official - official-sensitive - protected type: string version: description: Current version for optimistic concurrency type: integer type: object listAIAgents_200_response_agents_inner: example: assignedSkills: - assignedSkills - assignedSkills agentId: 046b6c7f-0b8a-43b9-b35d-6489e6daee91 guardrailPreset: guardrailPreset modelId: modelId description: description hasOverlay: true createdAt: 2000-01-23 04:56:07+00:00 longContext: true name: name temperature: 0.8008281904610115 maxTokens: 6 isGlobal: true group: group allowedTools: - allowedTools - allowedTools updatedAt: 2000-01-23 04:56:07+00:00 properties: agentId: format: uuid type: string name: type: string description: type: string group: type: string modelId: type: string temperature: type: number maxTokens: type: integer allowedTools: items: type: string type: array assignedSkills: items: type: string type: array longContext: type: boolean guardrailPreset: type: string isGlobal: type: boolean hasOverlay: type: boolean createdAt: format: date-time type: string updatedAt: format: date-time type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: 'Enter your Bearer token in the format: `Bearer `. Obtain your API token from the QuantCDN dashboard under Profile > API Tokens.' scheme: bearer type: http