API Reference Overview - Agent-CoreX Docs

Agent-CoreX API Reference

The Agent-CoreX API provides three core operations for discovering and executing tools:

Retrieve Tools - Find tools by natural language query
Get Tool - Get detailed information about a specific tool
Execute Tool - Run a tool with specified parameters

Authentication

All API requests require authentication using your API key.

API Key Setup

Get your API key from dashboard.agent-corex.com

Authentication Methods

Header (Recommended)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.agent-corex.com/retrieve_tools?query=...

Query Parameter

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

Environment Variable

export AGENT_COREX_API_KEY="your_api_key"

Base URL

https://api.agent-corex.com/v1

All endpoints are prefixed with this base URL.

Common Response Format

All responses follow a standard format:

Success Response (2xx)

{
  "success": true,
  "data": {
    // endpoint-specific data
  },
  "meta": {
    "request_id": "req_123abc",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Response (4xx, 5xx)

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Query parameter is required",
    "details": {
      "parameter": "query",
      "reason": "missing"
    }
  },
  "meta": {
    "request_id": "req_456def",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Error Codes

Code	HTTP	Meaning
`INVALID_REQUEST`	400	Missing or invalid parameters
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Permission denied
`NOT_FOUND`	404	Tool or resource not found
`RATE_LIMITED`	429	Too many requests
`SERVER_ERROR`	500	Internal server error

Retrieve Tools

GET /retrieve_tools Find available tools using natural language.

Query Parameters

Parameter	Type	Required	Default	Max
`query`	string	Yes	-	500 chars
`top_k`	integer	No	5	50
`filter`	object	No	-	-
`user_id`	string	No	current	-

Example Request

curl -X GET "https://api.agent-corex.com/v1/retrieve_tools" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Create a GitHub pull request and deploy to AWS",
    "top_k": 5
  }'

Example Response

{
  "success": true,
  "data": {
    "tools": [
      {
        "name": "create-pull-request",
        "server": "github-mcp",
        "score": 0.98,
        "description": "Create a new pull request on GitHub",
        "inputSchema": {
          "type": "object",
          "properties": {
            "repository": { "type": "string" },
            "title": { "type": "string" },
            "from_branch": { "type": "string" },
            "to_branch": { "type": "string" }
          },
          "required": ["repository", "title", "from_branch", "to_branch"]
        }
      },
      {
        "name": "deploy-to-aws",
        "server": "aws-mcp",
        "score": 0.95,
        "description": "Deploy application to AWS",
        "inputSchema": { /* ... */ }
      }
    ],
    "query_time_ms": 45,
    "total_tools_searched": 156
  }
}

Get Tool

GET /tools/{tool_name} Get detailed information about a specific tool.

Path Parameters

Parameter	Type	Required
`tool_name`	string	Yes

Example Request

curl -X GET "https://api.agent-corex.com/v1/tools/create-pull-request" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "name": "create-pull-request",
    "server": "github-mcp",
    "description": "Create a new pull request on GitHub",
    "category": "version-control",
    "tags": ["github", "git", "pr", "collaboration"],
    "inputSchema": {
      "type": "object",
      "properties": {
        "repository": {
          "type": "string",
          "description": "Repository in owner/repo format"
        },
        "title": {
          "type": "string",
          "description": "Pull request title"
        },
        "from_branch": {
          "type": "string",
          "description": "Source branch"
        },
        "to_branch": {
          "type": "string",
          "description": "Target branch"
        },
        "body": {
          "type": "string",
          "description": "Optional PR description"
        }
      },
      "required": ["repository", "title", "from_branch", "to_branch"]
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "pr_number": { "type": "integer" },
        "pr_url": { "type": "string" },
        "status": { "type": "string" }
      }
    },
    "examples": [
      {
        "input": {
          "repository": "owner/repo",
          "title": "Add new feature",
          "from_branch": "feature/new",
          "to_branch": "main"
        },
        "output": {
          "pr_number": 123,
          "pr_url": "https://github.com/owner/repo/pull/123",
          "status": "open"
        }
      }
    ],
    "authentication_required": "github_token",
    "rate_limit": {
      "requests_per_hour": 60
    }
  }
}

Execute Tool

POST /execute_tool Execute a tool with specified parameters.

Request Body

Field	Type	Required	Description
`tool_name`	string	Yes	Name of the tool to execute
`params`	object	Yes	Tool-specific parameters
`timeout`	integer	No	Timeout in milliseconds (default: 30000)
`user_id`	string	No	Override current user

Example Request

curl -X POST "https://api.agent-corex.com/v1/execute_tool" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "create-pull-request",
    "params": {
      "repository": "owner/repo",
      "title": "Fix critical bug",
      "from_branch": "hotfix/bug-123",
      "to_branch": "main",
      "body": "This PR fixes a critical production bug"
    },
    "timeout": 30000
  }'

Example Response

{
  "success": true,
  "data": {
    "tool_name": "create-pull-request",
    "status": "success",
    "result": {
      "pr_number": 123,
      "pr_url": "https://github.com/owner/repo/pull/123",
      "created_at": "2024-01-15T10:30:00Z",
      "author": "bot-user"
    },
    "execution_time_ms": 245,
    "tokens_used": {
      "input": 150,
      "output": 200
    }
  }
}

Rate Limiting

Agent-CoreX enforces rate limits based on your plan:

Free Tier

1,000 requests/month
10 requests/minute
100 concurrent requests

Pro Tier

100,000 requests/month
100 requests/minute
1,000 concurrent requests

Enterprise

Custom limits
Dedicated support
SLA: 99.99% uptime

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642262400

When rate limited (429 status):

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retry_after": 60
  }
}

Pagination

For list endpoints, use limit and offset:

curl "https://api.agent-corex.com/v1/tools?limit=10&offset=20"

Response

{
  "data": {
    "items": [...],
    "pagination": {
      "limit": 10,
      "offset": 20,
      "total": 156,
      "has_more": true
    }
  }
}

Filtering

Use filters to narrow results:

curl "https://api.agent-corex.com/v1/retrieve_tools" \
  -d '{
    "query": "deploy",
    "filter": {
      "server": "aws-mcp",
      "category": "infrastructure",
      "min_score": 0.85
    }
  }'

Webhooks & Async Operations

For long-running operations, use webhooks:

Register Webhook

curl -X POST "https://api.agent-corex.com/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://your-domain.com/webhooks/agent-corex",
    "events": ["tool.execution.completed", "tool.execution.failed"]
  }'

Webhook Payload

{
  "event": "tool.execution.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "execution_id": "exec_abc123",
    "tool_name": "create-pull-request",
    "status": "success",
    "result": { /* ... */ }
  }
}

SDK Usage

The Agent-CoreX SDK abstracts API complexity:

JavaScript

import { AgentCorex } from 'agent-corex';

const agent = new AgentCorex({
  apiKey: process.env.AGENT_COREX_API_KEY
});

const tools = await agent.retrieveTools({
  query: "Create a GitHub PR",
  topK: 5
});

const result = await agent.executeTool({
  toolName: 'create-pull-request',
  params: { /* ... */ }
});

Python

from agent_corex import AgentCorex

agent = AgentCorex(api_key="your_api_key")

tools = agent.retrieve_tools(
    query="Create a GitHub PR",
    top_k=5
)

result = agent.execute_tool(
    tool_name="create-pull-request",
    params={}
)

Best Practices

1. Always use specific queries

✅ Good: “Create a GitHub PR, deploy to AWS, notify Slack” ❌ Bad: “Do stuff”

2. Handle errors gracefully

try {
  const result = await agent.executeTool({
    toolName: 'create-pull-request',
    params: { /* ... */ }
  });
} catch (error) {
  if (error.code === 'TOOL_NOT_FOUND') {
    // Tool not connected
  } else if (error.code === 'RATE_LIMITED') {
    // Retry with backoff
  }
}

3. Batch requests efficiently

// Execute multiple tools in parallel
const results = await Promise.all(
  tools.map(tool => 
    agent.executeTool({
      toolName: tool.name,
      params: { /* ... */ }
    })
  )
);

4. Cache tool lists

// Tools don't change frequently
const tools = await agent.retrieveTools({
  query: "deploy"
  // Cache for 1 hour
});

Next Steps

Retrieve Tools Endpoint

Deep dive into the tool discovery API.

Execute Tool Endpoint

Execute tools and handle responses.

OpenAPI Specification

Complete OpenAPI 3.0 specification.

Code Examples

Real-world examples and workflows.

Need help? Check our FAQ or contact support

API Reference

​Agent-CoreX API Reference

​Authentication

​API Key Setup

​Authentication Methods

​Environment Variable

​Base URL

​Common Response Format

​Success Response (2xx)

​Error Response (4xx, 5xx)

​Error Codes

​Retrieve Tools

​Query Parameters

​Example Request

​Example Response

​Get Tool

​Path Parameters

​Example Request

​Example Response

​Execute Tool

​Request Body

​Example Request

​Example Response

​Rate Limiting

​Free Tier

​Pro Tier

​Enterprise

​Rate Limit Headers

​Pagination

​Response

​Filtering

​Webhooks & Async Operations

​Register Webhook

​Webhook Payload

​SDK Usage

​JavaScript

​Python

​Best Practices

​Next Steps

Retrieve Tools Endpoint

Execute Tool Endpoint

OpenAPI Specification

Code Examples

Agent-CoreX API Reference

Authentication

API Key Setup

Authentication Methods

Environment Variable

Base URL

Common Response Format

Success Response (2xx)

Error Response (4xx, 5xx)

Error Codes

Retrieve Tools

Query Parameters

Example Request

Example Response

Get Tool

Path Parameters

Example Request

Example Response

Execute Tool

Request Body

Example Request

Example Response

Rate Limiting

Free Tier

Pro Tier

Enterprise

Rate Limit Headers

Pagination

Response

Filtering

Webhooks & Async Operations

Register Webhook

Webhook Payload

SDK Usage

JavaScript

Python

Best Practices

Next Steps