Backend API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The Backend API provides a RESTful interface for the NeXify AI platform, facilitating communication between the frontend, external integrations, and the autonomous AI engine. It encompasses external public routes, administrative controls, and specialized AI master chat functionalities. The API architecture leverages FastAPI to handle high-concurrency requests and integrates with MongoDB for CRM data and Supabase for platform governance.
Sources: services/api/routes/api_v1_routes.py:1-8, services/ops/policies/openapi.json:1-8, frontend/product-landing/src/pages/Docs.tsx:4-6
External API v1
The External API provides programmatic access for third-party integrations using API-Key-based authentication. These routes use the /api/v1/ prefix and support features such as rate limiting and scoped permissions.
Authentication and Security
External requests require a valid API key passed via the X-API-Key header. The system validates the key against a stored SHA3-256 hash. API keys are associated with specific scopes (e.g., contacts:read, leads:write) to enforce granular access control.
Core External Endpoints
| Endpoint | Method | Scope | Description |
|---|---|---|---|
/api/v1/health | GET | None | Returns operational status and timestamp. |
/api/v1/contacts | GET | contacts:read | Lists contacts with search and pagination support. |
/api/v1/contacts | POST | contacts:write | Creates a new contact document in MongoDB. |
/api/v1/leads | POST | leads:write | Registers a new lead for processing. |
/api/v1/webhooks | POST | webhooks:write | Registers a webhook for event notifications. |
/api/v1/stats | GET | stats:read | Provides aggregated counts for contacts, leads, and quotes. |
Sources: services/api/routes/api_v1_routes.py:117-313, services/api/tests/test_iteration_66.py:35-43
NeXify AI Master Chat API
The AI Master Chat API serves as the primary interface for autonomous interaction. It facilitates communication with Agent Zero (the Master Agent) and various specialized workers.
Chat Architecture
The chat system uses a streaming response mechanism. It connects to OpenRouter (specifically the nexify_provider/nexify-pro model) and incorporates a "Brain-First" mandate by querying the vector database for relevant context before generating responses.
AI Tool Execution
The AI Master can execute server-side tools through a JSON-based command structure. These tools allow the agent to perform administrative tasks, search the brain, or manage system workers.
| Tool Name | Parameters | Purpose |
|---|---|---|
execute_shell | command | Executes shell commands (max 15s). |
search_brain | query | Performs semantic search on brain.db. |
send_email | to, subject, body | Dispatches emails via Resend. |
oracle_create_task | title, description | Creates a task in the Supabase governance system. |
Sources: services/api/routes/nexify_ai_routes.py:220-278, services/api/tests/test_iteration_66.py:97-160
Admin and Operations API
Administrative endpoints are secured via JWT tokens and provide high-level visibility into platform health and business metrics.
System Monitoring
The /api/admin/nexify-ai/status endpoint aggregates health data from multiple services including Qdrant, Supabase, MongoDB, and system hardware metrics (disk/memory usage).
Product and Billing Endpoints
These endpoints provide data for the frontend landing pages and customer portals regarding service offerings and pricing.
| Path | Method | Data Returned |
|---|---|---|
/api/product/tariffs | GET | Pricing for Starter and Growth agents. |
/api/product/faq | GET | List of 18+ Frequently Asked Questions. |
/api/booking/slots | GET | Available time slots for a specific date. |
/api/billing/invoices | GET | List of generated customer invoices. |
Sources: services/api/tests/test_iteration_17.py:34-78, services/ops/policies/openapi.json:62-79
Conclusion
The Backend API endpoints are structured to ensure high security through scoped API keys and JWT authentication while maintaining autonomous capabilities via the NeXify AI Master routes. By integrating specialized tools and context-aware memory, the API enables Agent Zero to manage the entire platform lifecycle from lead generation to project delivery.
Sources: services/api/routes/nexify_ai_routes.py:61-125, services/api/routes/api_v1_routes.py:1-6