{ "openapi": "3.1.0", "info": { "title": "Agentics API", "description": "Unified AI Inference, Audio, Image Generation, and VPN Proxy Platform", "version": "1.0.0", "termsOfService": "https://agentics.co.za/terms", "contact": { "name": "Agentics", "url": "https://agentics.co.za/contact", "email": "connor@agentics.co.za" }, "license": { "name": "Proprietary", "url": "https://agentics.co.za/terms" } }, "servers": [ { "url": "https://api.agentics.co.za", "description": "Production" } ], "externalDocs": { "description": "Documentation", "url": "https://agentics.co.za/docs" }, "x-api-version": "2026-06-14", "x-payment-info": { "schemes": [ "x402", "mpp" ], "currency": "ZAR", "discovery": "https://api.agentics.co.za/discovery/resources" }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Authentication" }, { "name": "Inference" }, { "name": "Images" }, { "name": "Audio" }, { "name": "Live Transcription" }, { "name": "Agent" }, { "name": "Realtime" }, { "name": "Orb" }, { "name": "Embeddings" }, { "name": "Research" }, { "name": "Glance" }, { "name": "VPN" }, { "name": "Connectors" } ], "paths": { "/v1/auth/register": { "post": { "tags": [ "Authentication" ], "operationId": "postAuthRegister", "summary": "Register a new user", "description": "Create a new user account with email and password", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "User email address" }, "password": { "type": "string", "description": "Password (min 8 characters)" }, "username": { "type": "string", "description": "Username" } }, "required": [ "email", "password", "username" ] } } } } } }, "/v1/auth/login": { "post": { "tags": [ "Authentication" ], "operationId": "postAuthLogin", "summary": "Login", "description": "Authenticate with email and password to receive access tokens", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "User email address" }, "password": { "type": "string", "description": "User password" } }, "required": [ "email", "password" ] } } } } } }, "/v1/auth/hardware-auth": { "post": { "tags": [ "Authentication" ], "operationId": "postAuthHardwareauth", "summary": "Hardware Authentication", "description": "Authenticate using a hardware ID for device-based auth", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "application": { "type": "string", "description": "Application name" }, "hardwareId": { "type": "string", "description": "Unique hardware identifier" } }, "required": [ "hardwareId" ] } } } } } }, "/v1/auth/refresh": { "post": { "tags": [ "Authentication" ], "operationId": "postAuthRefresh", "summary": "Refresh Token", "description": "Exchange a refresh token for a new access token", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "refreshToken": { "type": "string", "description": "Valid refresh token" } }, "required": [ "refreshToken" ] } } } } } }, "/v1/auth/profile": { "get": { "tags": [ "Authentication" ], "operationId": "getAuthProfile", "summary": "Get Profile", "description": "Retrieve the authenticated user's profile", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/auth/api-keys": { "post": { "tags": [ "Authentication" ], "operationId": "postAuthApikeys", "summary": "Create API Key", "description": "Generate a new API key for programmatic access", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name for the API key" } }, "required": [ "name" ] } } } } }, "get": { "tags": [ "Authentication" ], "operationId": "getAuthApikeys", "summary": "List API Keys", "description": "Retrieve all API keys for the authenticated user", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/models": { "get": { "tags": [ "Inference" ], "operationId": "getModels", "summary": "List Models", "description": "Get a list of all available text generation models", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/generate": { "post": { "tags": [ "Inference" ], "operationId": "postGenerate", "summary": "Generate Text", "description": "Generate text completion from a prompt", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxTokens": { "type": "integer", "description": "Maximum tokens to generate" }, "model": { "type": "string", "description": "Model to use" }, "prompt": { "type": "string", "description": "The prompt to generate from" }, "systemPrompt": { "type": "string", "description": "System prompt for context" }, "temperature": { "type": "number", "description": "Sampling temperature (0-2)" } }, "required": [ "prompt" ] } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "Inference" ], "operationId": "postChatCompletions", "summary": "Chat Completions", "description": "OpenAI-compatible chat completions endpoint", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "max_tokens": { "type": "integer", "description": "Maximum tokens to generate" }, "messages": { "type": "array", "description": "Array of message objects with role and content", "items": { "type": "string" } }, "model": { "type": "string", "description": "Model to use" }, "stream": { "type": "boolean", "description": "Enable streaming response" }, "temperature": { "type": "number", "description": "Sampling temperature (0-2)" } }, "required": [ "messages" ] } } } } } }, "/v1/images/models": { "get": { "tags": [ "Images" ], "operationId": "getImagesModels", "summary": "List Image Models", "description": "Get a list of all available image generation models", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/images/generations": { "post": { "tags": [ "Images" ], "operationId": "postImagesGenerations", "summary": "Generate Image", "description": "Generate images from text prompts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "description": "Output format: url or b64_json" }, "height": { "type": "integer", "description": "Image height in pixels" }, "model": { "type": "string", "description": "Model to use (AgenPics, Flux, Juggernaut, SDXL, Realism, Anime, etc.)" }, "n": { "type": "integer", "description": "Number of images to generate" }, "negative_prompt": { "type": "string", "description": "Things to avoid in the image" }, "prompt": { "type": "string", "description": "Text description of the image to generate" }, "ratio": { "type": "string", "description": "Aspect ratio (1:1, 16:9, 9:16, etc.)" }, "style": { "type": "string", "description": "Style preset for AgenPics model (photorealistic, cinematic, anime, oil-painting, watercolor, concept-art, pixel-art, cyberpunk, fantasy, noir, vaporwave, steampunk, gothic, minimalist, surreal, ukiyo-e, art-deco, sketch, pop-art, ethereal, logo)" }, "width": { "type": "integer", "description": "Image width in pixels" } }, "required": [ "prompt" ] } } } } } }, "/v1/audio/voices": { "get": { "tags": [ "Audio" ], "operationId": "getAudioVoices", "summary": "List Voices", "description": "Get a list of all available TTS voices", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/audio/tts": { "post": { "tags": [ "Audio" ], "operationId": "postAudioTts", "summary": "Text-to-Speech", "description": "Convert text to speech audio", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outputBase64": { "type": "boolean", "description": "Return base64 encoded audio" }, "quality": { "type": "integer", "description": "Audio quality (1-100)" }, "speed": { "type": "number", "description": "Speech speed multiplier" }, "text": { "type": "string", "description": "Text to convert to speech" }, "voice": { "type": "string", "description": "Voice to use" } }, "required": [ "text" ] } } } } } }, "/v1/audio/stt": { "post": { "tags": [ "Audio" ], "operationId": "postAudioStt", "summary": "Speech-to-Text", "description": "Transcribe audio to text", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file": { "type": "string", "description": "Audio file to transcribe (WAV, MP3, etc.)" }, "language": { "type": "string", "description": "Language code (e.g., 'en', 'es')" } }, "required": [ "file" ] } } } } } }, "/v1/audio/live/status": { "get": { "tags": [ "Live Transcription" ], "operationId": "getAudioLiveStatus", "summary": "Live Status", "description": "Check the status of the live transcription service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/audio/live/ws": { "ws": { "tags": [ "Live Transcription" ], "operationId": "wsAudioLiveWs", "summary": "Live Transcription WebSocket", "description": "WebSocket endpoint for real-time audio transcription. Send audio chunks, receive transcription events.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/v1/agent/tools": { "get": { "tags": [ "Agent" ], "operationId": "getAgentTools", "summary": "List Tools", "description": "Get a list of all available agent tools", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/agent/message": { "post": { "tags": [ "Agent" ], "operationId": "postAgentMessage", "summary": "Agent Message", "description": "Send a message to the AI agent for processing", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "array", "description": "Previous conversation context", "items": { "type": "string" } }, "maxTokens": { "type": "integer", "description": "Maximum response tokens" }, "message": { "type": "string", "description": "Message to the agent" }, "tools": { "type": "array", "description": "Tools to enable for this request", "items": { "type": "string" } } }, "required": [ "message" ] } } } } } }, "/v1/agent/search": { "post": { "tags": [ "Agent" ], "operationId": "postAgentSearch", "summary": "Web Search", "description": "Perform a web search and return results", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "maxResults": { "type": "integer", "description": "Maximum results to return" }, "query": { "type": "string", "description": "Search query" } }, "required": [ "query" ] } } } } } }, "/v1/agent/bash": { "post": { "tags": [ "Agent" ], "operationId": "postAgentBash", "summary": "Execute Bash", "description": "Execute a bash command in a sandboxed environment", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "command": { "type": "string", "description": "Bash command to execute" }, "timeout": { "type": "integer", "description": "Timeout in seconds" } }, "required": [ "command" ] } } } } } }, "/v1/realtime/status": { "get": { "tags": [ "Realtime" ], "operationId": "getRealtimeStatus", "summary": "Realtime Status", "description": "Check the status and capabilities of the realtime agent service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/realtime": { "ws": { "tags": [ "Realtime" ], "operationId": "wsRealtime", "summary": "Realtime Agent WebSocket", "description": "WebSocket endpoint for real-time voice-enabled AI agent. Send raw float32 audio at 16kHz mono, receive text events and float32 TTS audio at 22050Hz.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/v1/orb/session": { "post": { "tags": [ "Orb" ], "operationId": "postOrbSession", "summary": "Create Orb Session", "description": "Create a secure session token for embedding the Orb widget. The token is valid for 5 minutes and can only be used once.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain where the Orb will be embedded (must be whitelisted)" }, "model": { "type": "string", "description": "LLM model for the Orb" }, "origin": { "type": "string", "description": "Full origin URL" }, "voice": { "type": "string", "description": "TTS voice" } }, "required": [ "domain" ] } } } } } }, "/v1/orb/embed": { "get": { "tags": [ "Orb" ], "operationId": "getOrbEmbed", "summary": "Embed Orb Widget", "description": "Returns the embeddable Orb HTML/JS widget. Use in an iframe with the session token from /v1/orb/session.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/orb/secure-ws": { "ws": { "tags": [ "Orb" ], "operationId": "wsOrbSecurews", "summary": "Orb Secure WebSocket", "description": "WebSocket endpoint for the embedded Orb. Uses the secure token generated from /v1/orb/embed for authentication.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/v1/embeddings/generate": { "post": { "tags": [ "Embeddings" ], "operationId": "postEmbeddingsGenerate", "summary": "Generate Embeddings", "description": "Generate vector embeddings for text", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "Text to generate embeddings for" } }, "required": [ "text" ] } } } } } }, "/v1/embeddings/add": { "post": { "tags": [ "Embeddings" ], "operationId": "postEmbeddingsAdd", "summary": "Add Embedding", "description": "Add text and its embedding to a group for later search", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "type": "string", "description": "Group name to store in" }, "metadata": { "type": "object", "description": "Optional metadata" }, "text": { "type": "string", "description": "Text to store" } }, "required": [ "group", "text" ] } } } } } }, "/v1/embeddings/search": { "post": { "tags": [ "Embeddings" ], "operationId": "postEmbeddingsSearch", "summary": "Search Embeddings", "description": "Search for similar text using semantic search", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "group": { "type": "string", "description": "Group to search in" }, "limit": { "type": "integer", "description": "Maximum results" }, "query": { "type": "string", "description": "Search query" } }, "required": [ "group", "query" ] } } } } } }, "/v1/embeddings/groups": { "get": { "tags": [ "Embeddings" ], "operationId": "getEmbeddingsGroups", "summary": "List Groups", "description": "List all embedding groups for the authenticated user", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/research/status": { "get": { "tags": [ "Research" ], "operationId": "getResearchStatus", "summary": "Research Status", "description": "Check the status and capabilities of the search and research service", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/research/search": { "post": { "tags": [ "Research" ], "operationId": "postResearchSearch", "summary": "Web Search", "description": "Multi-engine web search with automatic fallback across SearXNG, DuckDuckGo, Brave, Startpage, Google, Bing, and Ecosia. Supports content enrichment via the contents parameter.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contents": { "type": "object", "description": "Content enrichment options (text, highlights, summary)" }, "numResults": { "type": "integer", "description": "Number of results to return" }, "query": { "type": "string", "description": "Search query" }, "type": { "type": "string", "description": "Search type (auto, keyword, deep)" } }, "required": [ "query" ] } } } } } }, "/v1/research/contents": { "post": { "tags": [ "Research" ], "operationId": "postResearchContents", "summary": "Get Contents", "description": "Fetch and extract content from one or more URLs. Supports text extraction, highlight extraction, and summarization.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "highlights": { "type": "string", "description": "Extract relevant highlights" }, "summary": { "type": "object", "description": "Generate summary with optional query" }, "text": { "type": "string", "description": "Extract full text (true) or with options {maxCharacters}" }, "urls": { "type": "array", "description": "Array of URLs to fetch content from", "items": { "type": "string" } } }, "required": [ "urls" ] } } } } } }, "/v1/research/findSimilar": { "post": { "tags": [ "Research" ], "operationId": "postResearchFindSimilar", "summary": "Find Similar", "description": "Find pages similar to a given URL by extracting its title and searching for related content.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "numResults": { "type": "integer", "description": "Number of similar results" }, "url": { "type": "string", "description": "URL to find similar pages for" } }, "required": [ "url" ] } } } } } }, "/v1/research/answer": { "post": { "tags": [ "Research" ], "operationId": "postResearchAnswer", "summary": "Quick Answer", "description": "Get a quick answer synthesized from multiple search results with source citations.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "numResults": { "type": "integer", "description": "Number of sources to consider" }, "query": { "type": "string", "description": "Question to answer" } }, "required": [ "query" ] } } } } } }, "/v1/research/deep": { "post": { "tags": [ "Research" ], "operationId": "postResearchDeep", "summary": "Start Deep Research", "description": "Start an asynchronous deep research task. The system iteratively searches, fetches content, analyzes with LLM, identifies gaps, and follows up until comprehensive coverage is achieved. Returns a task ID for polling progress.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Research query or topic" }, "systemPrompt": { "type": "string", "description": "Custom system prompt for research analysis" } }, "required": [ "query" ] } } } } } }, "/v1/research/deep/:taskId": { "get": { "tags": [ "Research" ], "operationId": "getResearchDeep", "summary": "Poll Research Progress", "description": "Poll the progress and results of a deep research task. Returns phases, progress percentage, and the final answer when complete.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/glance/status": { "get": { "tags": [ "Glance" ], "operationId": "getGlanceStatus", "summary": "Glance Status", "description": "Check the status and available presets of the Glance service.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/glance/scrape": { "post": { "tags": [ "Glance" ], "operationId": "postGlanceScrape", "summary": "Structured Scrape", "description": "Fetch a URL and optionally crawl within the same origin. Returns a structured result with origin, seed, per-page title and text, depth, byte counts, and stats.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "concurrency": { "type": "integer", "description": "Override concurrent fetches" }, "depth": { "type": "integer", "description": "Override max crawl depth (0 = only seed)" }, "excludeRegex": { "type": "array", "description": "Regex filters for URLs to exclude", "items": { "type": "string" } }, "includeRegex": { "type": "array", "description": "Regex filters for URLs to include", "items": { "type": "string" } }, "pages": { "type": "integer", "description": "Override max pages to crawl" }, "perPage": { "type": "integer", "description": "Override max text characters per page" }, "preset": { "type": "string", "description": "Preset to start from" }, "sameOrigin": { "type": "boolean", "description": "Restrict crawl to seed origin" }, "timeoutMs": { "type": "integer", "description": "Per-request timeout in ms" }, "totalTimeoutMs": { "type": "integer", "description": "Total crawl budget in ms" }, "url": { "type": "string", "description": "Target URL (http or https)" }, "userAgent": { "type": "string", "description": "Override User-Agent header" } }, "required": [ "url" ] } } } } } }, "/v1/glance/text": { "post": { "tags": [ "Glance" ], "operationId": "postGlanceText", "summary": "Flattened Text", "description": "Same scrape as /v1/glance/scrape but returns only the concatenated body text, ideal for feeding straight into an LLM context window.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preset": { "type": "string", "description": "Preset to start from" }, "url": { "type": "string", "description": "Target URL (http or https)" } }, "required": [ "url" ] } } } } } }, "/v1/glance/flat": { "post": { "tags": [ "Glance" ], "operationId": "postGlanceFlat", "summary": "Flat Markdown", "description": "Returns a titled markdown-ish concat of every crawled page, separated by --- dividers. Useful for LLM prompts that want page boundaries preserved.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "preset": { "type": "string", "description": "Preset to start from" }, "url": { "type": "string", "description": "Target URL (http or https)" } }, "required": [ "url" ] } } } } } }, "/v1/vpn/servers": { "get": { "tags": [ "VPN" ], "operationId": "getVpnServers", "summary": "List VPN Servers", "description": "Get a list of available VPN servers and regions", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "/v1/vpn/setup": { "post": { "tags": [ "VPN" ], "operationId": "postVpnSetup", "summary": "Setup VPN", "description": "Initialize VPN service by fetching latest server configurations", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/v1/vpn/connect": { "post": { "tags": [ "VPN" ], "operationId": "postVpnConnect", "summary": "Connect to VPN", "description": "Establish a proxy connection through a VPN server. Returns proxy credentials for routing traffic.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "proxyType": { "type": "string", "description": "Proxy type: socks5 or http" }, "server": { "type": "string", "description": "Server name to connect to" } }, "required": [ "server" ] } } } } } }, "/v1/vpn/status": { "get": { "tags": [ "VPN" ], "operationId": "getVpnStatus", "summary": "VPN Status", "description": "Get status of your active VPN proxy sessions", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/vpn/disconnect": { "post": { "tags": [ "VPN" ], "operationId": "postVpnDisconnect", "summary": "Disconnect VPN Session", "description": "Disconnect a specific VPN proxy session", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/v1/connectors/email/providers": { "get": { "tags": [ "Connectors" ], "operationId": "getConnectorsEmailProviders", "summary": "Suggest Provider Settings", "description": "Resolve common provider IMAP/SMTP defaults from an email address (Gmail, Outlook, Yahoo, iCloud, Zoho, Fastmail, ProtonMail bridge).", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connectors/email/test": { "post": { "tags": [ "Connectors" ], "operationId": "postConnectorsEmailTest", "summary": "Test Email Credentials", "description": "Validate IMAP login and SMTP authentication without persisting credentials.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "emailAddress": { "type": "string" }, "imapHost": { "type": "string" }, "imapPassword": { "type": "string" }, "imapPort": { "type": "integer" }, "imapTls": { "type": "boolean" }, "imapUsername": { "type": "string" }, "smtpHost": { "type": "string" }, "smtpPassword": { "type": "string" }, "smtpPort": { "type": "integer" }, "smtpTls": { "type": "boolean" }, "smtpUsername": { "type": "string" } }, "required": [ "emailAddress", "imapHost", "imapPassword", "imapPort", "smtpHost", "smtpPort" ] } } } } } }, "/v1/connectors/email": { "post": { "tags": [ "Connectors" ], "operationId": "postConnectorsEmail", "summary": "Connect Email Account", "description": "Verify credentials, encrypt and persist them, and trigger an initial sync of recent messages. Set domainWide=true to span an entire domain.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowCalendar": { "type": "boolean" }, "allowOutbound": { "type": "boolean" }, "autonomyLevel": { "type": "string", "description": "draft | review | full" }, "displayName": { "type": "string" }, "domainWide": { "type": "boolean" }, "emailAddress": { "type": "string" }, "imapHost": { "type": "string" }, "imapPassword": { "type": "string" }, "imapPort": { "type": "integer" }, "imapTls": { "type": "boolean" }, "label": { "type": "string" }, "smtpHost": { "type": "string" }, "smtpPort": { "type": "integer" }, "smtpTls": { "type": "boolean" } }, "required": [ "emailAddress", "imapHost", "imapPassword", "imapPort", "smtpHost", "smtpPort" ] } } } } }, "get": { "tags": [ "Connectors" ], "operationId": "getConnectorsEmail", "summary": "List Email Connectors", "description": "Return all email connectors configured for the authenticated user.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connectors/email/:id": { "get": { "tags": [ "Connectors" ], "operationId": "getConnectorsEmail", "summary": "Get Email Connector", "description": "Get Email Connector", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "tags": [ "Connectors" ], "operationId": "putConnectorsEmail", "summary": "Update Email Connector", "description": "Update autonomy level, permissions, label, display name or rotate IMAP/SMTP credentials.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ] }, "delete": { "tags": [ "Connectors" ], "operationId": "deleteConnectorsEmail", "summary": "Disconnect Email Account", "description": "Remove a connector and purge its cached messages and drafts.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connectors/email/:id/sync": { "post": { "tags": [ "Connectors" ], "operationId": "postConnectorsEmailSync", "summary": "Force Sync", "description": "Re-fetch the most recent envelope set from IMAP.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/v1/connectors/email/:id/messages": { "get": { "tags": [ "Connectors" ], "operationId": "getConnectorsEmailMessages", "summary": "List Recent Messages", "description": "Returns the latest cached messages, refreshing from IMAP on demand. Cached entries auto-expire after 30 days.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connectors/email/:id/messages/:msgId": { "get": { "tags": [ "Connectors" ], "operationId": "getConnectorsEmailMessages", "summary": "Get Full Message", "description": "Get Full Message", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/connectors/email/:id/send": { "post": { "tags": [ "Connectors" ], "operationId": "postConnectorsEmailSend", "summary": "Send Email", "description": "Send an outbound message immediately. Honors per-connector permissions and autonomy settings.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "bcc": { "type": "array", "items": { "type": "string" } }, "cc": { "type": "array", "items": { "type": "string" } }, "html": { "type": "string" }, "inReplyTo": { "type": "string" }, "replyTo": { "type": "string" }, "subject": { "type": "string" }, "text": { "type": "string" }, "to": { "type": "array", "description": "List of recipient email addresses", "items": { "type": "string" } } }, "required": [ "to" ] } } } } } }, "/v1/connectors/email/:id/drafts": { "get": { "tags": [ "Connectors" ], "operationId": "getConnectorsEmailDrafts", "summary": "List Drafts", "description": "Return draft replies awaiting approval. Filter via ?status=pending|approved|rejected|sent.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Connectors" ], "operationId": "postConnectorsEmailDrafts", "summary": "Create Draft", "description": "Create a draft response. Used by the agent layer to stage replies for human review under draft or review autonomy.", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/v1/connectors/email/:id/drafts/:draftId/approve": { "post": { "tags": [ "Connectors" ], "operationId": "postConnectorsEmailDraftsApprove", "summary": "Approve and Send Draft", "description": "Approve and Send Draft", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/v1/connectors/email/:id/drafts/:draftId/reject": { "post": { "tags": [ "Connectors" ], "operationId": "postConnectorsEmailDraftsReject", "summary": "Reject Draft", "description": "Reject Draft", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/v1/connectors/email/:id/drafts/:draftId": { "delete": { "tags": [ "Connectors" ], "operationId": "deleteConnectorsEmailDrafts", "summary": "Delete Draft", "description": "Delete Draft", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "API key (prefixed ag_) or JWT as a bearer token." }, "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://api.agentics.co.za/v1/auth/oauth/authorize", "tokenUrl": "https://api.agentics.co.za/v1/auth/oauth/token", "scopes": { "inference:read": "Run inference", "inference:write": "Create completions and media", "account:read": "Read account" } } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Unique key so a mutating request can be safely retried." }, "ApiVersion": { "name": "API-Version", "in": "header", "required": false, "schema": { "type": "string", "example": "2026-06-14" }, "description": "Date-based API version." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Machine-readable error code." }, "message": { "type": "string", "description": "Human-readable explanation." }, "type": { "type": "string", "description": "Error category." } } } } } }