Direct API Access

This page documents the raw HTTP protocol for WarpGrep (morph-warp-grep-v2.1). Use it to build a custom harness in any language. The API follows the OpenAI chat completions format with native tool calling. The model has its tools built in, so you do not pass a tools array. The model returns structured tool_calls, you execute them locally, and you send results back as tool messages. The tool schemas below are for reference so you know what to implement locally. For a complete implementation, see the Python Guide or the Python agent example. For TypeScript SDK wrappers, see Agent Tool.

Message Flow

The agent runs a multi-turn conversation with max 6 turns using OpenAI-compatible tool calling:

user → assistant (tool_calls) → tool results → assistant (tool_calls) → ... → finish

Step	Role	Content
1	`user`	Repo structure + search query
2	`assistant`	`tool_calls` array (structured JSON)
3	`tool`	One message per tool call result
4+	…	Repeat until `finish` is called

Initial User Message

The first user message contains two parts:

Repository structure — flat list of absolute paths (depth 2)
Search query — what the agent needs to find

<repo_structure>
/home/user/myproject
/home/user/myproject/README.md
/home/user/myproject/package.json
/home/user/myproject/src
/home/user/myproject/src/auth
/home/user/myproject/src/auth/login.py
/home/user/myproject/src/auth/session.py
/home/user/myproject/src/db
/home/user/myproject/src/utils
/home/user/myproject/tests
/home/user/myproject/config.py
/home/user/myproject/main.py
</repo_structure>

<search_string>
Find where user authentication is implemented
</search_string>

The repo structure must be flat absolute paths, one per line. First line is the repo root. No indentation, no tree characters. Directories have no trailing /.

API Call

The model has its tools built in — you do not need to pass a tools array. Just send the messages and the model returns structured tool_calls.

curl -X POST https://api.morphllm.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "morph-warp-grep-v2.1",
    "messages": [
      {"role": "user", "content": "<repo_structure>\n...\n</repo_structure>\n\n<search_string>\nFind auth middleware\n</search_string>"}
    ],
    "temperature": 0.0,
    "max_tokens": 2048
  }'

Logged in? Your API key will auto-fill above. Otherwise, get it from your dashboard.

Agent Response Format

The model responds with a standard OpenAI tool_calls array. No XML parsing needed.

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "morph-warp-grep-v2.1",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "chatcmpl-tool-abc123",
          "type": "function",
          "function": {
            "name": "grep_search",
            "arguments": "{\"pattern\": \"(auth.*middleware|middleware.*auth)\", \"path\": \".\", \"glob\": \"*.{py,yml,json,yaml,y}\"}"
          }
        }
      ]
    },
    "finish_reason": "tool_calls"
  }],
  "usage": {
    "prompt_tokens": 1180,
    "total_tokens": 1245,
    "completion_tokens": 65
  }
}

The content field is null on tool-call turns. Read only the tool_calls array. The finish_reason will be "tool_calls" when the model wants you to execute tools.

Execute each tool call locally and send results back as tool messages:

[
  {"role": "tool", "tool_call_id": "call_abc123", "content": "src/auth/login.py:45:def authenticate(username, password):"},
  {"role": "tool", "tool_call_id": "call_def456", "content": "login.py\nsession.py\nmiddleware/"}
]

Tool Definitions

The model calls these tools internally — you don’t need to pass them in the request. However, you need to implement each tool locally to execute the calls the model returns:

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "list_directory",
            "description": "Execute ls or find commands to explore directory structure. Max 500 results. Common junk directories are excluded automatically.",
            "parameters": {
                "type": "object",
                "properties": {
                    "command": {
                        "type": "string",
                        "description": "Full ls or find command (e.g. ls -la src/, find . -maxdepth 2 -type f -name '*.py', find . -type d, ls -d */)."
                    }
                },
                "required": ["command"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "grep_search",
            "description": "Search for a regex pattern in file contents. Returns matching lines with file paths and line numbers. Case-insensitive by default. Respects .gitignore.",
            "parameters": {
                "type": "object",
                "properties": {
                    "pattern": {
                        "type": "string",
                        "description": "Regex pattern to search for in file contents (e.g. 'class\\s+\\w+Error', 'import|require|from', 'def (get|set|update)_user')."
                    },
                    "path": {
                        "type": "string",
                        "description": "File or directory to search in. Defaults to current working directory."
                    },
                    "glob": {
                        "type": "string",
                        "description": "Glob pattern to filter files (e.g. '*.py', '*.{ts,tsx,js,jsx,py,go}', 'src/**/*.go', '!*.test.*')."
                    },
                    "limit": {
                        "type": "integer",
                        "description": "Limit output to first N matching lines. Shows all matches if not specified."
                    },
                    "case_sensitive": {
                        "type": "boolean",
                        "description": "Make the match case-sensitive. Defaults to false (case-insensitive). The model may send this as the string \"true\"/\"false\", so coerce it (see robustness note)."
                    }
                },
                "required": ["pattern"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "glob",
            "description": "Find files by name/extension using glob patterns. Returns absolute paths sorted by modification time (newest first). Respects .gitignore. Max 100 results.",
            "parameters": {
                "type": "object",
                "properties": {
                    "pattern": {
                        "type": "string",
                        "description": "Glob pattern to match files (e.g. '*.py', 'src/**/*.js', '*.{ts,tsx}', 'test_*.py')."
                    },
                    "path": {
                        "type": "string",
                        "description": "Directory to search in. Defaults to repository root."
                    }
                },
                "required": ["pattern"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "read",
            "description": "Read entire files or specific line ranges using absolute paths.",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "File path to read, using absolute path (e.g. '/home/ubuntu/repo/src/main.py' or windows path)."
                    },
                    "lines": {
                        "type": "string",
                        "description": "Optional line range (e.g. '1-50' or '1-20,45-80'). Omit to read entire file."
                    }
                },
                "required": ["path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "finish",
            "description": "Submit final answer with all relevant code locations. Include imports and over-include rather than miss context.",
            "parameters": {
                "type": "object",
                "properties": {
                    "files": {
                        "type": "string",
                        "description": "One file per line as path:lines (e.g. '/home/user/repo/src/auth.py:1-15,25-50\\n/home/user/repo/src/user.py'). Paths are absolute, matching the paths from the repo structure. Omit line range to include entire file."
                    }
                },
                "required": ["files"]
            }
        }
    },
]

Coerce argument types and tolerate off-schema arguments. The model sometimes sends arguments whose JSON type differs from the schema above, or arguments not listed here at all. Treat every argument leniently:

limit and case_sensitive may arrive as strings ("50", "false") rather than an integer or boolean. Coerce before use.
grep_search may emit output_lines (a string alias for limit) or output_context_lines (ripgrep -C context). Map them to your limit/context handling.
Ignore any argument you do not recognize rather than erroring. Only pattern (for grep_search) is guaranteed.

Parse defensively: read known keys with fallbacks, and never assume a value’s type from the schema alone.

Executing Tools

When the model returns tool_calls, execute each one locally and return the output as a tool message. Here’s a minimal Python implementation:

import subprocess, os, glob as globmod

def _as_bool(v):
    return str(v).strip().lower() in ("true", "1", "yes") if v is not None else False

def _as_int(v):
    try:
        return int(v)
    except (TypeError, ValueError):
        return None

def execute_tool(name: str, args: dict, repo_root: str) -> str:
    if name == "grep_search":
        cmd = ["rg", "--line-number", "--no-heading", "--color=never", "-C", "1"]
        # case-insensitive by default; the model may flip it via case_sensitive
        # (which can arrive as a string like "false", so coerce it).
        if not _as_bool(args.get("case_sensitive")):
            cmd.append("-i")
        cmd.append(args["pattern"])
        cmd.append(args.get("path", repo_root))
        if "glob" in args:
            cmd.extend(["--glob", args["glob"]])
        # limit may arrive as an int or string; output_lines is an alias the model sometimes emits.
        limit = _as_int(args.get("limit", args.get("output_lines")))
        if limit is not None:
            cmd.extend(["--max-count", str(limit)])
        result = subprocess.run(cmd, capture_output=True, text=True, cwd=repo_root)
        lines = result.stdout.strip().split("\n")
        return "\n".join(lines[:200])

    elif name == "read":
        path = args["path"] if os.path.isabs(args["path"]) else os.path.join(repo_root, args["path"])
        with open(path, "r") as f:
            all_lines = f.readlines()
        if "lines" in args:
            selected = []
            for part in args["lines"].split(","):
                start, end = map(int, part.split("-"))
                selected.extend(
                    f"{i}|{all_lines[i-1].rstrip()}"
                    for i in range(start, min(end + 1, len(all_lines) + 1))
                )
            return "\n".join(selected[:800])
        return "\n".join(f"{i+1}|{l.rstrip()}" for i, l in enumerate(all_lines[:800]))

    elif name == "list_directory":
        result = subprocess.run(
            args["command"], shell=True, capture_output=True, text=True, cwd=repo_root
        )
        return "\n".join(result.stdout.strip().split("\n")[:500])

    elif name == "glob":
        pattern = os.path.join(args.get("path", repo_root), "**", args["pattern"])
        matches = sorted(globmod.glob(pattern, recursive=True), key=os.path.getmtime, reverse=True)
        return "\n".join(matches[:100])

    elif name == "finish":
        output = []
        for spec in args["files"].strip().split("\n"):
            if ":" in spec and not spec.endswith(":*"):
                fpath, ranges = spec.rsplit(":", 1)
            else:
                fpath, ranges = spec.replace(":*", ""), None
            fpath = fpath if os.path.isabs(fpath) else os.path.join(repo_root, fpath)
            with open(fpath) as f:
                all_lines = f.readlines()
            if ranges:
                for part in ranges.split(","):
                    start, end = map(int, part.split("-"))
                    output.extend(all_lines[start - 1 : end])
            else:
                output.extend(all_lines)
        return "".join(output)

Turn Counter

After tool results, add a user message with a turn counter and context budget:

You have used 1 turn and have 5 remaining.
<context_budget>97% (525K/540K chars)</context_budget>

Turn messages by turn number:

Turn	Message
1	`You have used 1 turn and have 5 remaining`
2	`You have used 2 turns and have 4 remaining`
…	…
5	`You have used 5 turns, you only have 1 turn remaining. You have run out of turns to explore the code base and MUST call the finish tool now`

If the model does not call finish within 6 turns, the search failed. Return an empty result to your caller.

Output Limits

Tools enforce output limits to prevent context explosion:

Tool	Max Lines	On Exceed
`grep_search`	200	Truncate with warning
`list_directory`	200	Truncate with warning
`read`	800	Truncate with warning
`glob`	100 files	Truncate

Complete Example

Putting it all together — a full agent loop:

import json
import openai

# YOUR_API_KEY will auto-fill if logged in
client = openai.OpenAI(base_url="https://api.morphllm.com/v1", api_key="YOUR_API_KEY")
repo_root = "/home/user/myapp"

messages = [
    {
        "role": "user",
        "content": (
            "<repo_structure>\n"
            "/home/user/myapp\n"
            "/home/user/myapp/src\n"
            "/home/user/myapp/src/auth\n"
            "/home/user/myapp/src/api\n"
            "/home/user/myapp/src/models\n"
            "/home/user/myapp/tests\n"
            "/home/user/myapp/package.json\n"
            "</repo_structure>\n\n"
            "<search_string>\nFind where JWT tokens are validated\n</search_string>"
        ),
    }
]

max_turns = 6
for turn in range(max_turns):
    response = client.chat.completions.create(
        model="morph-warp-grep-v2.1",
        messages=messages,
        temperature=0.0,
        max_tokens=2048,
    )
    msg = response.choices[0].message
    messages.append(msg)

    if not msg.tool_calls:
        break

    for tc in msg.tool_calls:
        args = json.loads(tc.function.arguments)
        result = execute_tool(tc.function.name, args, repo_root)

        if tc.function.name == "finish":
            # result contains the final file contents — done
            print(result)
            break

        messages.append({"role": "tool", "tool_call_id": tc.id, "content": result})
    else:
        # Add turn counter after all tool results
        remaining = max_turns - turn - 1
        turn_msg = f"You have used {turn + 1} turn{'s' if turn else ''} and have {remaining} remaining"
        if remaining <= 1:
            turn_msg += ". You have run out of turns to explore the code base and MUST call the finish tool now"
        messages.append({"role": "user", "content": turn_msg})
        continue
    break

Get Started

Models

API Reference

Integrations

Message Flow

Initial User Message

API Call

Agent Response Format

Tool Definitions

Executing Tools

Turn Counter

Output Limits

Complete Example

​Message Flow

​Initial User Message

​API Call

​Agent Response Format

​Tool Definitions

​Executing Tools

​Turn Counter

​Output Limits

​Complete Example

Message Flow

Initial User Message

API Call

Agent Response Format

Tool Definitions

Executing Tools

Turn Counter

Output Limits

Complete Example