system-prompts-and-models-o.../universal-ai-artifacts/openapi/openapi.yaml
Sahiix@1 ad88de25e3
Update universal-ai-artifacts/openapi/openapi.yaml
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2025-10-02 09:02:18 +04:00

928 lines
25 KiB
YAML

openapi: 3.0.3
info:
title: Universal AI Agent API
version: "1.0.0"
description: |
OpenAPI 3.0 specification generated from the Universal AI Agent API reference.
servers:
- url: https://your-domain.com
description: Production server
security:
- bearerAuth: []
paths:
/health:
get:
summary: Health check
description: Returns service health and connected subsystems.
responses:
'200':
description: Health status
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
/system/info:
get:
summary: System information
security:
- bearerAuth: []
responses:
'200':
description: System information
content:
application/json:
schema:
$ref: '#/components/schemas/SystemInfoResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
/auth/login:
post:
summary: Login and obtain JWT tokens
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LoginRequest'
responses:
'200':
description: Login success
content:
application/json:
schema:
$ref: '#/components/schemas/LoginResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
/chat:
post:
summary: Standard chat
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ChatRequest'
responses:
'200':
description: Chat response
content:
application/json:
schema:
$ref: '#/components/schemas/ChatResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
/stream:
get:
summary: Streaming chat (SSE)
description: Server-Sent Events stream of chat tokens/chunks.
security:
- bearerAuth: []
parameters:
- in: query
name: message
required: true
schema:
type: string
- in: query
name: optimizePrompt
required: false
schema:
type: boolean
default: false
responses:
'200':
description: text/event-stream output
content:
text/event-stream:
schema:
type: string
description: Stream of SSE events with `data: {"type": "start|chunk|end", ...}`
'401':
$ref: '#/components/responses/UnauthorizedError'
/conversations:
get:
summary: List conversation history
security:
- bearerAuth: []
parameters:
- in: query
name: limit
schema: { type: integer, default: 50, minimum: 1 }
- in: query
name: offset
schema: { type: integer, default: 0, minimum: 0 }
- in: query
name: userId
schema: { type: string }
responses:
'200':
description: Conversation list
content:
application/json:
schema:
$ref: '#/components/schemas/ConversationsResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
/rag/ingest:
post:
summary: Ingest documents to the RAG collection
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RagIngestRequest'
responses:
'200':
description: Ingest result
content:
application/json:
schema:
$ref: '#/components/schemas/RagIngestResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
/rag/search:
post:
summary: Semantic search over RAG documents
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RagSearchRequest'
responses:
'200':
description: Search results
content:
application/json:
schema:
$ref: '#/components/schemas/RagSearchResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
/rag/answer:
post:
summary: RAG-enhanced answer generation
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RagAnswerRequest'
responses:
'200':
description: Generated answer with sources and context
content:
application/json:
schema:
$ref: '#/components/schemas/RagAnswerResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
/agents/execute:
post:
summary: Execute a multi-agent task
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AgentsExecuteRequest'
responses:
'200':
description: Task execution results
content:
application/json:
schema:
$ref: '#/components/schemas/AgentsExecuteResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
/agents/task/{taskId}:
get:
summary: Get multi-agent task status
security:
- bearerAuth: []
parameters:
- in: path
name: taskId
required: true
schema: { type: string }
responses:
'200':
description: Task status
content:
application/json:
schema:
$ref: '#/components/schemas/AgentTaskStatusResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
/voice/tts:
post:
summary: Text to speech
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TTSRequest'
responses:
'200':
description: TTS result
content:
application/json:
schema:
$ref: '#/components/schemas/TTSResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
/voice/command:
post:
summary: Process a voice command (text intent processing)
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceCommandRequest'
responses:
'200':
description: Intent and action
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceCommandResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
/voice/autopilot:
post:
summary: Control autopilot mode
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceAutopilotRequest'
responses:
'200':
description: Autopilot status
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceAutopilotResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
/plugins:
get:
summary: List available plugins
security:
- bearerAuth: []
responses:
'200':
description: Plugin list
content:
application/json:
schema:
$ref: '#/components/schemas/PluginsListResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
/plugins/{pluginName}/execute:
post:
summary: Execute a plugin action
security:
- bearerAuth: []
parameters:
- in: path
name: pluginName
required: true
schema: { type: string }
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PluginExecuteRequest'
responses:
'200':
description: Plugin execution result
content:
application/json:
schema:
$ref: '#/components/schemas/PluginExecuteResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'404':
$ref: '#/components/responses/NotFoundError'
/plugins/install:
post:
summary: Install a plugin
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PluginInstallRequest'
responses:
'200':
description: Installation result
content:
application/json:
schema:
$ref: '#/components/schemas/PluginInstallResponse'
'400':
$ref: '#/components/responses/ValidationError'
'401':
$ref: '#/components/responses/UnauthorizedError'
/analytics/dashboard:
get:
summary: Get dashboard analytics
security:
- bearerAuth: []
responses:
'200':
description: Dashboard data
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsDashboardResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
/analytics/metrics:
get:
summary: Get system metrics timeseries
security:
- bearerAuth: []
parameters:
- in: query
name: timeRange
schema:
type: string
enum: ["1h", "24h", "7d", "30d"]
default: "24h"
- in: query
name: metric
schema:
type: string
enum: ["requests", "performance", "errors", "users"]
responses:
'200':
description: Metrics timeseries
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyticsMetricsResponse'
'401':
$ref: '#/components/responses/UnauthorizedError'
/analytics/export:
get:
summary: Export analytics data
security:
- bearerAuth: []
parameters:
- in: query
name: format
schema:
type: string
enum: ["json", "csv"]
default: "json"
- in: query
name: timeRange
schema:
type: string
enum: ["1h", "24h", "7d", "30d"]
default: "24h"
responses:
'200':
description: File download
content:
application/octet-stream:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/UnauthorizedError'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
responses:
UnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
NotFoundError:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ValidationError:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
ErrorResponse:
type: object
properties:
error:
type: boolean
example: true
message:
type: string
code:
type: string
timestamp:
type: string
format: date-time
requestId:
type: string
HealthResponse:
type: object
properties:
status:
type: string
example: healthy
uptime:
type: integer
memory:
type: string
connections:
type: object
additionalProperties: { type: string }
features:
type: object
properties:
rag: { type: boolean }
voice: { type: boolean }
plugins: { type: boolean }
multiAgent: { type: boolean }
SystemInfoResponse:
type: object
properties:
version: { type: string }
nodeVersion: { type: string }
platform: { type: string }
architecture: { type: string }
environment: { type: string }
features:
type: array
items: { type: string }
limits:
type: object
properties:
maxRequestSize: { type: string }
rateLimit:
type: object
properties:
window: { type: integer }
max: { type: integer }
LoginRequest:
type: object
required: [email, password]
properties:
email: { type: string, format: email }
password: { type: string }
mfaCode: { type: string, nullable: true }
LoginResponse:
type: object
properties:
success: { type: boolean }
accessToken: { type: string }
refreshToken: { type: string }
sessionId: { type: string }
user:
type: object
properties:
id: { type: string }
email: { type: string }
roles:
type: array
items: { type: string }
mfaEnabled: { type: boolean }
ChatRequest:
type: object
required: [message]
properties:
message: { type: string }
optimizePrompt: { type: boolean, default: false }
context: { type: string, nullable: true }
userId: { type: string, nullable: true }
ChatResponse:
type: object
properties:
response: { type: string }
metadata:
type: object
properties:
model: { type: string }
tokens: { type: integer }
responseTime: { type: integer }
optimized: { type: boolean }
conversationId: { type: string }
ConversationsResponse:
type: object
properties:
conversations:
type: array
items:
type: object
properties:
id: { type: string }
userId: { type: string }
messages:
type: array
items:
type: object
properties:
role: { type: string, enum: [user, assistant, system] }
content: { type: string }
timestamp: { type: string, format: date-time }
createdAt: { type: string, format: date-time }
updatedAt: { type: string, format: date-time }
total: { type: integer }
hasMore: { type: boolean }
RagIngestRequest:
type: object
required: [documents, collection]
properties:
documents:
type: array
items:
type: object
required: [id, content]
properties:
id: { type: string }
content: { type: string }
metadata:
type: object
additionalProperties: {}
collection: { type: string }
RagIngestResponse:
type: object
properties:
success: { type: boolean }
ingested: { type: integer }
failed: { type: integer }
collection: { type: string }
processingTime: { type: integer }
RagSearchRequest:
type: object
required: [query, collection]
properties:
query: { type: string }
collection: { type: string }
limit: { type: integer, default: 5 }
threshold: { type: number, format: float, nullable: true }
RagSearchResponse:
type: object
properties:
results:
type: array
items:
type: object
properties:
id: { type: string }
content: { type: string }
score: { type: number, format: float }
metadata:
type: object
additionalProperties: {}
query: { type: string }
totalResults: { type: integer }
searchTime: { type: integer }
RagAnswerRequest:
type: object
required: [question, collection]
properties:
question: { type: string }
collection: { type: string }
maxContext: { type: integer, default: 3 }
includeContext: { type: boolean, default: true }
RagAnswerResponse:
type: object
properties:
answer: { type: string }
sources:
type: array
items:
type: object
properties:
id: { type: string }
title: { type: string }
relevanceScore: { type: number, format: float }
context:
type: array
items:
type: object
properties:
content: { type: string }
source: { type: string }
confidence: { type: number, format: float }
AgentsExecuteRequest:
type: object
required: [task, agents]
properties:
task: { type: string }
agents:
type: array
items: { type: string }
parallel: { type: boolean, default: false }
maxIterations: { type: integer, default: 3 }
AgentsExecuteResponse:
type: object
properties:
success: { type: boolean }
taskId: { type: string }
results:
type: array
items:
type: object
properties:
agent: { type: string }
role: { type: string }
response: { type: string }
executionTime: { type: integer }
finalSynthesis: { type: string }
totalExecutionTime: { type: integer }
confidence: { type: number, format: float }
AgentTaskStatusResponse:
type: object
properties:
taskId: { type: string }
status: { type: string, enum: [queued, running, completed, failed] }
progress: { type: integer }
currentAgent: { type: string, nullable: true }
results:
type: array
items: { type: object }
startTime: { type: string, format: date-time }
endTime: { type: string, format: date-time, nullable: true }
TTSRequest:
type: object
required: [text, voice, language, voice, language]
properties:
text: { type: string }
voice: { type: string, example: neural }
language: { type: string, example: en-US }
speed: { type: number, default: 1.0 }
format: { type: string, enum: [mp3, wav, ogg], default: mp3 }
TTSResponse:
type: object
properties:
success: { type: boolean }
audioUrl: { type: string }
duration: { type: number }
format: { type: string }
size: { type: integer }
VoiceCommandRequest:
type: object
required: [command]
properties:
command: { type: string }
context: { type: string, nullable: true }
userId: { type: string, nullable: true }
VoiceCommandResponse:
type: object
properties:
success: { type: boolean }
command: { type: string }
intent: { type: string }
entities:
type: array
items: { type: string }
action: { type: string }
response: { type: string }
audioResponse: { type: string }
VoiceAutopilotRequest:
type: object
required: [mode]
properties:
mode:
type: string
enum: [start, stop, status]
context: { type: string, nullable: true }
preferences:
type: object
properties:
verbosity: { type: string, enum: [low, medium, high] }
autoExecute: { type: boolean }
VoiceAutopilotResponse:
type: object
properties:
success: { type: boolean }
mode: { type: string }
sessionId: { type: string }
status: { type: string }
capabilities:
type: array
items: { type: string }
PluginsListResponse:
type: object
properties:
plugins:
type: array
items:
type: object
properties:
name: { type: string }
version: { type: string }
description: { type: string }
category: { type: string }
status: { type: string }
permissions:
type: array
items: { type: string }
total: { type: integer }
PluginExecuteRequest:
type: object
required: [action, parameters]
properties:
action: { type: string }
parameters:
type: object
additionalProperties: {}
PluginExecuteResponse:
type: object
properties:
success: { type: boolean }
plugin: { type: string }
action: { type: string }
result:
type: object
additionalProperties: {}
executionTime: { type: integer }
PluginInstallRequest:
type: object
required: [source, package, version]
properties:
source: { type: string, enum: [npm, git, url] }
package: { type: string }
version: { type: string }
PluginInstallResponse:
type: object
properties:
success: { type: boolean }
plugin: { type: string }
version: { type: string }
status: { type: string }
message: { type: string }
AnalyticsDashboardResponse:
type: object
properties:
overview:
type: object
properties:
uptime: { type: integer }
totalRequests: { type: integer }
successRate: { type: string }
averageResponseTime: { type: integer }
activeUsers: { type: integer }
healthScore: { type: integer }
requests:
type: object
properties:
total: { type: integer }
successful: { type: integer }
failed: { type: integer }
byHour:
type: array
items: { type: integer }
topEndpoints:
type: array
items:
type: object
properties:
endpoint: { type: string }
requests: { type: integer }
averageTime: { type: integer }
errorRate: { type: number }
ai:
type: object
properties:
totalTokens: { type: integer }
totalCost: { type: number }
averageResponseTime: { type: integer }
topModels:
type: array
items:
type: object
properties:
model: { type: string }
requests: { type: integer }
tokens: { type: integer }
cost: { type: number }
AnalyticsMetricsResponse:
type: object
properties:
timeRange: { type: string }
metrics:
type: object
additionalProperties:
type: object
properties:
timestamps:
type: array
items: { type: string, format: date-time }
values:
type: array
items: { type: number }
x-websocket:
url: wss://your-domain.com
description: |
WebSocket API supports the following client messages: `auth`, `stream_chat`, `voice_command`, `plugin_execute`.
Server messages include: `auth_success`, `chat_response`, `stream_chunk`, `error`.