Skip to main content

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 2: Header Key

Method 3: Query Parameter

Method 4: Admin Key (For Admin Endpoints)


🌐 Base URL

All endpoints listed below are relative to this base URL.

📦 Tool Discovery Endpoints (6)

1. GET /retrieve_tools

Semantic search over tools by natural language query. Auth: Optional
Query Params:
  • query (string, required) - Natural language search query
  • top_k (integer, optional, default: 5) - Number of results to return
Try It: Example Response:

2. GET /tools

List all available tools with metadata. Auth: Optional
Query Params: None
Example Request:
Example Response:

3. GET /v2/retrieve_tools

Advanced V2/V3 hybrid retrieval with capability filtering. Auth: Optional
Query Params:
  • query (string, required)
  • top_k (integer, 1-20, default: 5)
  • use_hybrid_v3 (boolean, default: true) - Use V3 algorithm
Example Request:
Example Response:

4. GET /v2/capabilities

List all available MCP server capabilities. Auth: Optional
Query Params: None
Example Response:

5. GET /capabilities

List capabilities with tool counts. Auth: Optional
Example Response:

6. GET /tools/registry

Get all tools from the registry. Auth: Not required
Example Response:

⚙️ Tool Execution Endpoints (2)

7. POST /execute_tool

Execute a tool directly (admin only). Auth: Required (Admin)
Request Body:
  • tool (string, required) - Tool name
  • arguments (object, required) - Tool arguments
  • mode (string, optional) - Execution mode
Try It:

8. POST /jobs/submit

Submit async job for tool execution. Auth: Required
Request Body:
  • tool (string) - Tool name
  • arguments (object) - Tool arguments
Example Response:

🔌 MCP Server Management (8)

9. GET /mcp_servers

List all MCP servers with user state. Auth: Required
Example Response:

10. POST /mcp_servers/toggle

Toggle MCP server state. Auth: Required
Request Body:
  • server (string) - Server name
  • enabled (boolean) - Enable/disable

11. GET /mcp_registry

List all MCP servers from registry. Auth: Not required

12. GET /mcp_registry/

Get specific MCP server. Auth: Not required

13-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: Optional

18. GET /packs/

Get specific pack. Auth: Optional

19. GET /packs//servers

Get servers in a pack. Auth: Optional

20. POST /packs/enable

Enable all capabilities in a pack. Auth: Required
Request 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 required
Example Response:

33. POST /auth/login

Authenticate with API key. Auth: Required

34. POST /auth/cli/start

Start CLI authentication (device code flow). Auth: Not required
Example Response:

35. POST /auth/cli/poll

Poll CLI session status. Auth: Not required
Request 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: Optional
Request Body: Query details

39. GET /queries

Get user’s query history. Auth: Required
Query Params:
  • limit (integer, default: 50)

40. POST /tools/selection-log

Log tool selection/rejection. Auth: Optional

41. POST /observability/tool-logs

Ingest batch of tool logs. Auth: Optional

42. GET /observability/tool-insights

Get tool usage insights. Auth: Optional

43-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 required

48. PATCH /mcp-moderation/flags/

Resolve flag (admin). Auth: Required (Admin)

49. GET /mcp-moderation/servers//verification

Get server verification status. Auth: Not required

50. 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 required
Query Params:
  • sort_by - “recent”, “rating”
  • limit - Number of reviews

53. GET /mcp-moderation/servers/featured

Get featured servers. Auth: Not required

54. GET /mcp-moderation/moderation/dashboard

View moderation dashboard (admin). Auth: Required (Admin)

💳 Billing & Plans (5)

55. GET /billing/plans

Get available plans. Auth: Not required
Example Response:

56. GET /billing/user-limits

Get current user’s plan limits. Auth: Required
Example Response:

57. POST /billing/create-order

Create payment order (Razorpay). Auth: Required
Request Body:
  • plan_id (string)
Example Response:

58. POST /billing/verify-payment

Verify payment and update plan. Auth: Required
Request 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 required

65. POST /free-tools/run

Execute free tool. Auth: Optional
Request Body:
  • tool_slug (string) - Tool slug
  • input (object) - Tool input
  • user_identifier (string, optional)

66. POST /free-tools/install

Install free tool. Auth: Not required

67. GET /recommender/examples

Get recommendation examples. Auth: Not required

68. POST /recommender/status

Recommender service status. Auth: Not required

69. POST /recommender

Get AI-powered tool recommendation. Auth: Optional
Request Body:
  • query (string) - User query
Example Response:

70. GET /settings/embedding

Get embedding settings. Auth: Required

71. POST /settings/embedding

Save embedding settings. Auth: Required
Request Body:
  • provider (string) - “openai” or other
  • openai_model (string) - Model name

🎯 User Servers (3)

72. GET /user-servers/servers

Get user’s enabled servers. Auth: Required
Example Response:

73. POST /user-servers/servers

Sync user servers to backend. Auth: Required
Request 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: Required
Request Body:
  • tools (array) - Tools to index
  • skip_existing (boolean, optional)

76. POST /v2/track_installation

Track tool installation. Auth: Required
Request Body:
  • tool_name (string)
  • server (string)
  • pack_id (string, optional)

🤖 Agent Execution (1)

77. POST /agent/execute

Execute Vibe Coding task. Auth: Optional
Request 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/

🧪 Testing Endpoints

Use the interactive playgrounds above to test each endpoint directly. All examples use real request/response structures derived from the codebase.

📚 See Also