Rank Cookbook
Platform
Esc

    Type to search the documentation.

    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..."
}

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

    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}

    Register a server:

    {
  "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}
    {
  "success": true,
  "data": {
    "items": [
      {
        "id": 7,
        "name": "Aleex Gemini 2.5 Flash",
        "alias": "gemini-2.5-flash",
        "company_name": "Google",
        "max_input_tokens": 1048576,
        "max_output_tokens": 65536,
        "support_files": true,
        "reasoning": false
      }
    ],
    "pagination": {"total": 1, "count": 1, "per_page": 20, "current_page": 1, "total_pages": 1}
  }
}

    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.