Agents API

HTTP reference for managing AI agents — CRUD and clone, tool assignment, MCP servers, phases and the models agents run on.

All paths are relative to https://api.aleex-rank.ai/api/v2 and authenticate with X-API-Key: rk_... (see REST API). For the concepts behind agents, tools and MCP, read Agents, tools & MCP.

What an agent is

An agent is a configured worker: a model, a system prompt, a set of tools, optionally some MCP servers, and a phase it belongs to. Agents are either pentest agents (assigned to phases of a pentest) or general agents (used in Chat). Default agents ship with the platform; you can create your own or clone an existing one and customise it, subject to your tier’s agent limit.

List and filter agents

GET /agents
GET /agents/mine

GET /agents lists the agents available to you. Filter the pool when configuring a pentest phase:

GET /agents?type=pentest&phase_id=1

GET /agents/mine returns only the agents you own.

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 101,
        "name": "Recon Master",
        "description": "Passive reconnaissance specialist",
        "phase_id": 1,
        "phase_name": "Reconnaissance",
        "agent_type": "pentest",
        "is_default": true,
        "model": {"id": 7, "name": "Aleex Gemini 2.5 Flash"}
      }
    ],
    "pagination": {"total": 1, "count": 1, "per_page": 20, "current_page": 1, "total_pages": 1}
  }
}

Create, retrieve, update, delete

POST   /agents
GET    /agents/{id}
PATCH  /agents/{id}
DELETE /agents/{id}

Create an agent (fields are representative — model_id and phase_id are the key ones):

{
  "name": "Custom OSINT Agent",
  "description": "Gathers open-source intelligence on the target",
  "model_id": 7,
  "phase_id": 1,
  "agent_type": "pentest",
  "system_prompt": "You are an expert in passive reconnaissance...",
  "effort": "high",
  "thinking_enabled": true
}

PATCH /agents/{id} (or PUT) updates a mutable agent; DELETE /agents/{id} removes one you own. Default and protected agents cannot be deleted.

Reasoning: effort and thinking

Two optional fields tune how the agent’s model reasons. Both accept null (or can be omitted) to inherit the model’s default — see Agents, tools & MCP for the concept.

Field	Type	Values
`effort`	string \| null	`none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`
`thinking_enabled`	boolean \| null	`true` to force reasoning on, `false` to turn it off

Both POST /agents and PATCH /agents/{id} accept these fields, validated against the target model (the model_id in the request, or the agent’s current model):

The agent must have a model. Sending effort/thinking_enabled without one returns effort/thinking require a model.
effort must be one of the canonical values and be in the model’s effort_values; the model must have supports_effort: true. Otherwise you get This model does not support the effort parameter or Invalid effort value for this model.
thinking_enabled: true requires the model’s reasoning: true (This model does not support thinking).
thinking_enabled: false requires the model’s supports_thinking_toggle: true (Thinking cannot be disabled for this model).
Changing model_id without re-sending effort/thinking_enabled re-clamps any stored override the new model no longer accepts (effort falls back to the new default_effort, thinking falls back to inherit).

The agent detail (GET /agents/{id}) echoes both the overrides and the model capabilities so a UI can render valid choices:

{
  "effort": "high",
  "thinking_enabled": true,
  "supports_effort": true,
  "effort_values": ["low", "medium", "high"],
  "default_effort": "medium",
  "supports_thinking_toggle": true
}

Clone an agent

POST /agents/{id}/clone

Copies an existing agent — including its tools and MCP assignments — into a new agent you own, so you can tweak it without touching the original. This is the usual way to customise a default agent.

{
  "success": true,
  "data": {"id": 250, "name": "Recon Master (copy)", "cloned_from": 101}
}

Tools

GET    /agents/{id}/tools
POST   /agents/{id}/tools
DELETE /agents/{id}/tools/{toolId}
GET    /agents/{id}/available-tools

GET …/tools lists the agent’s assigned tools; GET …/available-tools lists tools you could add. Assign tools (body representative):

{"tool_ids": [29, 30]}

Each tool exposes a name, a description, a JSON-schema parameters object, a tool_type (e.g. browser, support) and an execution_mode (cloud, local or both).

Custom tools

Beyond assigning the built-in catalog, you can define your own local tools — commands that run on your machine through the CLI. These are managed as a first-class resource:

GET    /tools
POST   /tools
GET    /tools/{id}
PATCH  /tools/{id}
DELETE /tools/{id}

GET /tools lists the local tools you own. A tool wraps a shell command with {placeholder} parameters that the executor fills in at run time:

{
  "name": "shodan_host_lookup",
  "description": "Look up an IP address on Shodan",
  "command": "shodan host {ip_address}",
  "execution_mode": "local",
  "requires_api_key": true,
  "bootstrap": "shodan init {SHODAN_API_KEY}",
  "timeout_seconds": 60,
  "parameters": {
    "type": "object",
    "properties": {"ip_address": {"type": "string"}},
    "required": ["ip_address"]
  }
}

Once created, assign the tool to an agent (POST /agents/{id}/tools) or to a pentest phase. Because local tools execute on your host, they only run through the CLI’s local mode — the CLI’s rank tools create is the same operation, and the end-to-end walkthrough lives in Build a custom local tool. For where local tools run, see Agents, tools & MCP.

MCP servers

Agents can be extended with MCP servers — remote endpoints you own that expose extra tools dynamically. You declare your servers, then attach them to agents.

GET    /mcp-servers
POST   /mcp-servers
GET    /mcp-servers/{id}
PATCH  /mcp-servers/{id}
DELETE /mcp-servers/{id}

{
  "name": "my_burpsuite",
  "description": "Remote Burp Suite MCP",
  "transport_type": "streamable_http",
  "url": "https://mcp.example.com:8080/mcp",
  "headers": {"X-Custom": "value"},
  "auth_type": "bearer",
  "auth_config": {"token": "user-token-123"}
}

transport_type is streamable_http or sse (the stdio transport is reserved for future local CLI use). Server names are unique per user. Only servers with enabled: 1 can be attached to agents, and you can only manage your own.

Attach and detach servers on an agent:

GET    /agents/{id}/mcps
POST   /agents/{id}/mcps
DELETE /agents/{id}/mcps/{mcpId}

{"mcp_server_ids": [42]}

When a pentest runs, the streaming backend reads each agent’s tools and mcp_servers, connects to your MCP servers, discovers their tools and lets the model call them. MCP servers are available from Pro upwards.

Phases

GET /phases
GET /phases/pentest

GET /phases/pentest returns just the pentest phases (Reconnaissance, Enumeration, Analysis) you assign agents to; GET /phases returns all phases including the general (chat) phase.

Models

Agents run on a model. The models you can use depend on your tier.

GET    /models
GET    /models/{id}
GET    /models/mine
POST   /models/assign
DELETE /models/mine/{id}

GET /models lists the models available to your tier; GET /models/mine lists those assigned to you. Assign a model to yourself:

{"model_id": 7}

Each model advertises its reasoning capabilities, which are what constrain an agent’s effort and thinking_enabled (see above):

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 6,
        "name": "Aleex GPT-5",
        "alias": "gpt-5",
        "company_name": "OpenAI",
        "max_input_tokens": 400000,
        "max_output_tokens": 128000,
        "support_files": true,
        "reasoning": true,
        "supports_effort": true,
        "effort_values": ["minimal", "low", "medium", "high"],
        "default_effort": "medium",
        "supports_thinking_toggle": false
      }
    ],
    "pagination": {"total": 1, "count": 1, "per_page": 20, "current_page": 1, "total_pages": 1}
  }
}

Use effort_values to know which effort levels an agent on this model may set, default_effort for the inherited value, reasoning/supports_thinking_toggle to know whether thinking can be toggled.

Assigning agents to a pentest

Putting agents onto a pentest’s phases is done from the pentest, not here: POST /pentests/{id}/agents. See the Pentests API.