Complete Agent-CoreX API Reference
77 Endpoints organized by feature group with interactive playground.📋 Endpoint Summary by Group
Total: 77 Endpoints
🔐 Authentication
All protected endpoints require authentication using one of these methods:Method 1: Bearer Token (Recommended)
Method 2: Header Key
Method 3: Query Parameter
Method 4: Admin Key (For Admin Endpoints)
🌐 Base URL
📦 Tool Discovery Endpoints (6)
1. GET /retrieve_tools
Semantic search over tools by natural language query. Auth: OptionalQuery Params:
query(string, required) - Natural language search querytop_k(integer, optional, default: 5) - Number of results to return
2. GET /tools
List all available tools with metadata. Auth: OptionalQuery Params: None Example Request:
3. GET /v2/retrieve_tools
Advanced V2/V3 hybrid retrieval with capability filtering. Auth: OptionalQuery Params:
query(string, required)top_k(integer, 1-20, default: 5)use_hybrid_v3(boolean, default: true) - Use V3 algorithm
4. GET /v2/capabilities
List all available MCP server capabilities. Auth: OptionalQuery Params: None Example Response:
5. GET /capabilities
List capabilities with tool counts. Auth: OptionalExample Response:
6. GET /tools/registry
Get all tools from the registry. Auth: Not requiredExample Response:
⚙️ Tool Execution Endpoints (2)
7. POST /execute_tool
Execute a tool directly (admin only). Auth: Required (Admin)Request Body:
tool(string, required) - Tool namearguments(object, required) - Tool argumentsmode(string, optional) - Execution mode
8. POST /jobs/submit
Submit async job for tool execution. Auth: RequiredRequest Body:
tool(string) - Tool namearguments(object) - Tool arguments
🔌 MCP Server Management (8)
9. GET /mcp_servers
List all MCP servers with user state. Auth: RequiredExample Response:
10. POST /mcp_servers/toggle
Toggle MCP server state. Auth: RequiredRequest Body:
server(string) - Server nameenabled(boolean) - Enable/disable
11. GET /mcp_registry
List all MCP servers from registry. Auth: Not required12. GET /mcp_registry/
Get specific MCP server. Auth: Not required13-16. Admin MCP Registry Endpoints
Create, update, delete, and sync MCP registry entries. Auth: Required (Admin)- POST /admin/mcp_registry
- PATCH /admin/mcp_registry/
- DELETE /admin/mcp_registry/
- POST /admin/mcp_registry/sync-to-supabase
📦 Capabilities & Packs (15)
17. GET /packs
List all capability packs. Auth: Optional18. GET /packs/
Get specific pack. Auth: Optional19. GET /packs//servers
Get servers in a pack. Auth: Optional20. POST /packs/enable
Enable all capabilities in a pack. Auth: RequiredRequest Body:
pack_id(string) - Pack to enable
21-31. Custom Packs Endpoints (11)
Manage custom packs and servers. Auth: Required- POST /custom-packs/mcp-servers - Create custom server
- GET /custom-packs/mcp-servers - List custom servers
- POST /custom-packs/packs - Create custom pack
- GET /custom-packs/packs - List custom packs
- GET /custom-packs/packs/ - Get pack
- PATCH /custom-packs/packs/ - Update pack
- DELETE /custom-packs/packs/ - Delete pack
- PUT /custom-packs/packs//servers - Replace servers
- POST /custom-packs/packs//servers - Add server
- DELETE /custom-packs/packs//servers/ - Remove server
- GET /custom-packs/packs//install - Get install command
🔐 Authentication Endpoints (4)
32. GET /health
System health check. Auth: Not requiredExample Response:
33. POST /auth/login
Authenticate with API key. Auth: Required34. POST /auth/cli/start
Start CLI authentication (device code flow). Auth: Not requiredExample Response:
35. POST /auth/cli/poll
Poll CLI session status. Auth: Not requiredRequest Body:
device_code(string) - Device code from /auth/cli/start
36. POST /auth/cli/complete
Complete CLI authentication. Auth: Required (Supabase token in body)📊 Usage & Analytics (8)
37. POST /usage/event
Record usage event. Auth: Optional (Bearer token or API key)Request Body: Custom usage event structure
38. POST /query/log
Log query event. Auth: OptionalRequest Body: Query details
39. GET /queries
Get user’s query history. Auth: RequiredQuery Params:
limit(integer, default: 50)
40. POST /tools/selection-log
Log tool selection/rejection. Auth: Optional41. POST /observability/tool-logs
Ingest batch of tool logs. Auth: Optional42. GET /observability/tool-insights
Get tool usage insights. Auth: Optional43-45. MCP Analytics (3)
Track and view analytics. Auth Requirements Vary- POST /mcp-analytics/analytics/track - Public
- GET /mcp-analytics/servers//analytics - Admin
- GET /mcp-analytics/analytics/dashboard - Admin
- GET /mcp-analytics/analytics/search-trends - Admin
🚫 Moderation & Flagging (10)
46. POST /mcp-moderation/servers//flags
Flag server for review. Auth: Required (User ID)47. GET /mcp-moderation/servers//flags
Get server flags. Auth: Not required48. PATCH /mcp-moderation/flags/
Resolve flag (admin). Auth: Required (Admin)49. GET /mcp-moderation/servers//verification
Get server verification status. Auth: Not required50. PATCH /mcp-moderation/servers//verification
Update verification (admin). Auth: Required (Admin)51. POST /mcp-moderation/servers//reviews
Create server review. Auth: Required (User ID)52. GET /mcp-moderation/servers//reviews
Get server reviews. Auth: Not requiredQuery Params:
sort_by- “recent”, “rating”limit- Number of reviews
53. GET /mcp-moderation/servers/featured
Get featured servers. Auth: Not required54. GET /mcp-moderation/moderation/dashboard
View moderation dashboard (admin). Auth: Required (Admin)💳 Billing & Plans (5)
55. GET /billing/plans
Get available plans. Auth: Not requiredExample Response:
56. GET /billing/user-limits
Get current user’s plan limits. Auth: RequiredExample Response:
57. POST /billing/create-order
Create payment order (Razorpay). Auth: RequiredRequest Body:
plan_id(string)
58. POST /billing/verify-payment
Verify payment and update plan. Auth: RequiredRequest Body:
plan_id(string)razorpay_order_id(string)razorpay_payment_id(string)razorpay_signature(string)
59. POST /billing/webhook
Razorpay webhook handler. Auth: Webhook signature verification👥 Admin Management (4)
60. GET /admin/users
List all users. Auth: Required (Admin)61. GET /admin/users/
Get user details. Auth: Required (Admin)62. PATCH /admin/users//role
Update user role. Auth: Required (Admin)Request Body:
role(string) - “admin” or “user”
63. DELETE /admin/users/
Delete user. Auth: Required (Admin)🔧 Integrations (4)
64. GET /free-tools/status
Free tools service status. Auth: Not required65. POST /free-tools/run
Execute free tool. Auth: OptionalRequest Body:
tool_slug(string) - Tool sluginput(object) - Tool inputuser_identifier(string, optional)
66. POST /free-tools/install
Install free tool. Auth: Not required67. GET /recommender/examples
Get recommendation examples. Auth: Not required68. POST /recommender/status
Recommender service status. Auth: Not required69. POST /recommender
Get AI-powered tool recommendation. Auth: OptionalRequest Body:
query(string) - User query
70. GET /settings/embedding
Get embedding settings. Auth: Required71. POST /settings/embedding
Save embedding settings. Auth: RequiredRequest Body:
provider(string) - “openai” or otheropenai_model(string) - Model name
🎯 User Servers (3)
72. GET /user-servers/servers
Get user’s enabled servers. Auth: RequiredExample Response:
73. POST /user-servers/servers
Sync user servers to backend. Auth: RequiredRequest Body:
installed_servers(array)installed_packs(array)
74. POST /user-servers/sync-trigger
Trigger server sync. Auth: Required📈 Advanced Retrieval (4)
75. POST /v2/index_tools
Enrich and index tools. Auth: RequiredRequest Body:
tools(array) - Tools to indexskip_existing(boolean, optional)
76. POST /v2/track_installation
Track tool installation. Auth: RequiredRequest Body:
tool_name(string)server(string)pack_id(string, optional)
🤖 Agent Execution (1)
77. POST /agent/execute
Execute Vibe Coding task. Auth: OptionalRequest Body:
query(string)
📋 Quick Reference Table
✨ Features by Endpoint Type
🟢 Public (No Auth Required)
- GET /health
- GET /tools/registry
- GET /mcp_registry
- GET /mcp_registry/
- POST /auth/cli/start
- POST /auth/cli/poll
- GET /mcp-moderation/servers//flags
- GET /mcp-moderation/servers//verification
- GET /mcp-moderation/servers//reviews
- GET /mcp-moderation/servers/featured
- GET /billing/plans
- GET /free-tools/status
- POST /free-tools/install
- GET /recommender/examples
- POST /recommender/status
- POST /mcp-analytics/analytics/track
🟡 Optional Auth
- GET /retrieve_tools
- GET /tools
- GET /v2/retrieve_tools
- GET /v2/capabilities
- GET /capabilities
- GET /packs
- GET /packs/
- GET /packs//servers
- POST /usage/event
- POST /query/log
- POST /tools/selection-log
- POST /observability/tool-logs
- GET /observability/tool-insights
- POST /free-tools/run
- POST /recommender
- POST /agent/execute
🔴 Required Auth
- POST /auth/login
- POST /auth/cli/complete
- POST /jobs/submit
- GET /jobs/
- DELETE /jobs/
- GET /jobs
- GET /mcp_servers
- POST /mcp_servers/toggle
- GET /tools/installed
- All /custom-packs/* endpoints
- GET /queries
- POST /packs/enable
- All /admin/* endpoints
- All /billing/* endpoints (except GET /billing/plans)
- All authenticated /mcp-analytics/* endpoints
- All authenticated /mcp-moderation/* endpoints
- All /user-servers/* endpoints
- All /v2/* authenticated endpoints
- GET /settings/embedding
- POST /settings/embedding
🔐 Admin Only
- POST /execute_tool
- POST /admin/mcp_registry
- PATCH /admin/mcp_registry/
- DELETE /admin/mcp_registry/
- POST /admin/mcp_registry/sync-to-supabase
- GET /mcp-analytics/servers//analytics
- GET /mcp-analytics/analytics/dashboard
- GET /mcp-analytics/analytics/search-trends
- PATCH /mcp-moderation/flags/
- PATCH /mcp-moderation/servers//verification
- GET /mcp-moderation/moderation/dashboard
- GET /admin/users
- GET /admin/users/
- PATCH /admin/users//role
- DELETE /admin/users/