> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agent-corex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference Overview

> Complete Agent-CoreX API reference with endpoint documentation, code examples, authentication details, and OpenAPI specifications for all functionality

## Agent-CoreX API Reference

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

1. **[Retrieve Tools](#retrieve-tools)** - Find tools by natural language query
2. **[Get Tool](#get-tool)** - Get detailed information about a specific tool
3. **[Execute 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](https://dashboard.agent-corex.com/api-keys)

### Authentication Methods

**Header (Recommended)**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.agent-corex.com/retrieve_tools?query=...
```

**Query Parameter**

```bash theme={null}
curl "https://api.agent-corex.com/retrieve_tools?query=...&api_key=YOUR_API_KEY"
```

### Environment Variable

```bash theme={null}
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)

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

### Error Response (4xx, 5xx)

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
curl -X GET "https://api.agent-corex.com/v1/tools/create-pull-request" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "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

```bash theme={null}
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

```json theme={null}
{
  "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):

```json theme={null}
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "retry_after": 60
  }
}
```

***

## Pagination

For list endpoints, use `limit` and `offset`:

```bash theme={null}
curl "https://api.agent-corex.com/v1/tools?limit=10&offset=20"
```

### Response

```json theme={null}
{
  "data": {
    "items": [...],
    "pagination": {
      "limit": 10,
      "offset": 20,
      "total": 156,
      "has_more": true
    }
  }
}
```

***

## Filtering

Use filters to narrow results:

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "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

```javascript theme={null}
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

```python theme={null}
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

<Accordion title="1. Always use specific queries">
  ✅ Good: "Create a GitHub PR, deploy to AWS, notify Slack"
  ❌ Bad: "Do stuff"
</Accordion>

<Accordion title="2. Handle errors gracefully">
  ```javascript theme={null}
  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
    }
  }
  ```
</Accordion>

<Accordion title="3. Batch requests efficiently">
  ```javascript theme={null}
  // Execute multiple tools in parallel
  const results = await Promise.all(
    tools.map(tool => 
      agent.executeTool({
        toolName: tool.name,
        params: { /* ... */ }
      })
    )
  );
  ```
</Accordion>

<Accordion title="4. Cache tool lists">
  ```javascript theme={null}
  // Tools don't change frequently
  const tools = await agent.retrieveTools({
    query: "deploy"
    // Cache for 1 hour
  });
  ```
</Accordion>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Retrieve Tools Endpoint" href="/api-reference/retrieve-tools">
    Deep dive into the tool discovery API.
  </Card>

  <Card title="Execute Tool Endpoint" href="/api-reference/execute-tool">
    Execute tools and handle responses.
  </Card>

  <Card title="Code Examples" href="/examples/sample-queries">
    Real-world examples and workflows.
  </Card>
</CardGroup>

***

**Need help?** Check our [FAQ](#faq) or [contact support](mailto:support@agent-corex.com)