Skip to main content

​
Complete Agent-CoreX API Reference

77 Endpoints organized by feature group with interactive playground.

​
📋 Endpoint Summary by Group

GroupCountDescription
Tool Discovery6Retrieve, filter, and manage tools
Tool Execution2Execute tools and manage execution jobs
MCP Servers8Manage MCP server installations and registry
Capabilities & Packs15Enable capabilities, manage custom packs
Authentication4API key and CLI device-flow auth
Usage & Analytics8Track usage, view analytics dashboards
Moderation & Flagging10Flag servers, manage reviews and verification
Billing & Plans5Manage billing and plan upgrades
Admin Management4User and system administration
Integrations4Free tools, recommender, embeddings
Advanced Retrieval4V2/V3 hybrid tool retrieval
User Servers3Sync user’s installed servers/packs
System Health1Health check endpoint
Other3Agent execution, observability logs
Total: 77 Endpoints

​
🔐 Authentication

All protected endpoints require authentication using one of these methods: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.agent-corex.com/retrieve_tools?query=...

​
Method 2: Header Key

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.agent-corex.com/retrieve_tools?query=...

​
Method 3: Query Parameter

curl "https://api.agent-corex.com/retrieve_tools?query=...&api_key=YOUR_API_KEY"

​
Method 4: Admin Key (For Admin Endpoints)

curl -H "X-Admin-Key: ADMIN_KEY" \
  https://api.agent-corex.com/admin/users

​
🌐 Base URL

https://api.agent-corex.com
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: 
{
  "tools": [
    {
      "name": "create_pull_request",
      "server": "github-mcp",
      "score": 0.98,
      "description": "Create a new pull request on GitHub"
    }
  ],
  "query_time_ms": 45,
  "total_tools_searched": 156
}

​
2. GET /tools

List all available tools with metadata. Auth: Optional
Query Params: None Example Request: 
curl https://api.agent-corex.com/tools \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response: 
{
  "tools": [
    {
      "name": "create_pull_request",
      "server": "github-mcp",
      "description": "Create a new pull request"
    }
  ],
  "total": 156
}

​
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: 
curl "https://api.agent-corex.com/v2/retrieve_tools?query=deploy&top_k=10&use_hybrid_v3=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example Response: 
{
  "tools": [...],
  "selected_capability": "deployment",
  "capability_confidence": 0.95,
  "query_rewritten": "Deploy application to cloud platform",
  "recommended_mcps": ["aws-mcp", "terraform-mcp"],
  "query_id": "q_abc123"
}

​
4. GET /v2/capabilities

List all available MCP server capabilities. Auth: Optional
Query Params: None Example Response: 
{
  "capabilities": [
    {
      "server_name": "github-mcp",
      "description": "Git version control and GitHub operations"
    },
    {
      "server_name": "aws-mcp",
      "description": "AWS cloud infrastructure management"
    }
  ]
}

​
5. GET /capabilities

List capabilities with tool counts. Auth: Optional
Example Response: 
{
  "capabilities": [
    {
      "id": "git",
      "name": "Git & Version Control",
      "tool_count": 12
    }
  ]
}

​
6. GET /tools/registry

Get all tools from the registry. Auth: Not required
Example Response: 
{
  "tools": [
    {
      "name": "create_pr",
      "category": "version-control",
      "tags": ["github", "git"]
    }
  ]
}

​
⚙️ 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: 
{
  "job_id": "job_abc123",
  "status": "queued",
  "created_at": 1234567890
}

​
🔌 MCP Server Management (8)

​
9. GET /mcp_servers

List all MCP servers with user state. Auth: Required
Example Response: 
{
  "servers": [
    {
      "name": "github-mcp",
      "enabled": true,
      "installed": true
    }
  ]
}

​
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: 
{
  "status": "ok"
}

​
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: 
{
  "device_code": "ABC123",
  "verification_url": "https://agent-corex.com/auth/cli?code=ABC123",
  "expires_in": 1800
}

​
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: 
{
  "plans": [
    {
      "id": "free",
      "name": "Free",
      "price": 0,
      "limits": {
        "max_packs": 1,
        "max_servers_per_pack": 5
      }
    },
    {
      "id": "pro",
      "name": "Pro",
      "price": 99,
      "limits": {
        "max_packs": 10,
        "max_servers_per_pack": 50
      }
    }
  ]
}

​
56. GET /billing/user-limits

Get current user’s plan limits. Auth: Required
Example Response: 
{
  "plan": "pro",
  "max_packs": 10,
  "max_servers_per_pack": 50
}

​
57. POST /billing/create-order

Create payment order (Razorpay). Auth: Required
Request Body:
  • plan_id (string)
Example Response: 
{
  "order_id": "order_abc123",
  "amount": 9900,
  "currency": "INR",
  "key_id": "razorpay_key"
}

​
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: 
{
  "status": "success",
  "servers": ["github-mcp", "aws-mcp"],
  "tools": ["create_pr", "deploy"],
  "steps": ["Clone repo", "Make changes", "Create PR"],
  "cta": ["Install servers", "Run tools"]
}

​
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: 
{
  "enabled_packs": ["pack1", "pack2"],
  "enabled_servers": ["github-mcp", "aws-mcp"]
}

​
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

#MethodPathAuthDescription
1GET/retrieve_toolsOptSemantic tool search
2GET/toolsOptList all tools
3GET/v2/retrieve_toolsOptAdvanced retrieval
4GET/v2/capabilitiesOptList capabilities
5GET/capabilitiesOptCapabilities with counts
6GET/tools/registryNoTool registry
7POST/execute_toolYesExecute tool (admin)
8POST/jobs/submitYesSubmit async job
9GET/jobs/YesGet job status
10DELETE/jobs/YesCancel job
11GET/jobsYesList user jobs
12GET/mcp_serversYesList MCP servers
13POST/mcp_servers/toggleYesToggle server
14GET/tools/installedYesList installed tools
15GET/mcp_registryNoGet registry
16GET/mcp_registry/NoGet registry entry
17POST/admin/mcp_registryYesCreate registry entry
18PATCH/admin/mcp_registry/YesUpdate registry entry
19DELETE/admin/mcp_registry/YesDelete registry entry
20POST/admin/mcp_registry/sync-to-supabaseYesSync to Supabase
21GET/healthNoHealth check
22POST/auth/loginYesLogin
23POST/auth/cli/startNoStart CLI auth
24POST/auth/cli/pollNoPoll CLI status
25POST/auth/cli/completeYesComplete CLI auth
26GET/packsOptList packs
27GET/packs/OptGet pack
28GET/packs//serversOptGet pack servers
29POST/packs/enableYesEnable pack
30POST/custom-packs/mcp-serversYesCreate custom server
31GET/custom-packs/mcp-serversYesList custom servers
32POST/custom-packs/packsYesCreate custom pack
33GET/custom-packs/packsYesList custom packs
34GET/custom-packs/packs/YesGet custom pack
35PATCH/custom-packs/packs/YesUpdate custom pack
36DELETE/custom-packs/packs/YesDelete custom pack
37PUT/custom-packs/packs//serversYesReplace pack servers
38POST/custom-packs/packs//serversYesAdd server to pack
39DELETE/custom-packs/packs//servers/YesRemove server from pack
40GET/custom-packs/packs//installYesGet install command
41POST/usage/eventOptRecord usage
42POST/query/logOptLog query
43GET/queriesYesGet query history
44POST/tools/selection-logOptLog selection
45POST/mcp-analytics/analytics/trackNoTrack analytics
46GET/mcp-analytics/servers//analyticsYesGet analytics
47GET/mcp-analytics/analytics/dashboardYesAnalytics dashboard
48GET/mcp-analytics/analytics/search-trendsYesSearch trends
49POST/mcp-moderation/servers//flagsYesFlag server
50GET/mcp-moderation/servers//flagsNoGet flags
51PATCH/mcp-moderation/flags/YesResolve flag
52GET/mcp-moderation/servers//verificationNoGet verification
53PATCH/mcp-moderation/servers//verificationYesUpdate verification
54POST/mcp-moderation/servers//reviewsYesCreate review
55GET/mcp-moderation/servers//reviewsNoGet reviews
56GET/mcp-moderation/servers/featuredNoFeatured servers
57GET/mcp-moderation/moderation/dashboardYesModeration dashboard
58GET/billing/plansNoGet plans
59GET/billing/user-limitsYesGet user limits
60POST/billing/create-orderYesCreate order
61POST/billing/verify-paymentYesVerify payment
62POST/billing/webhookSpecialRazorpay webhook
63GET/admin/usersYesList users
64GET/admin/users/YesGet user
65PATCH/admin/users//roleYesUpdate role
66DELETE/admin/users/YesDelete user
67GET/free-tools/statusNoTool status
68POST/free-tools/runOptRun tool
69POST/free-tools/installNoInstall tool
70GET/recommender/examplesNoGet examples
71POST/recommender/statusNoStatus
72POST/recommenderOptGet recommendation
73GET/settings/embeddingYesGet settings
74POST/settings/embeddingYesSave settings
75POST/observability/tool-logsOptIngest logs
76GET/observability/tool-insightsOptGet insights
77GET/user-servers/serversYesGet servers
78POST/user-servers/serversYesSync servers
79POST/user-servers/sync-triggerYesTrigger sync
80POST/v2/index_toolsYesIndex tools
81POST/v2/track_installationYesTrack install
82POST/agent/executeOptExecute agent

​
✨ 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