WarpGrep API

Overview

WarpGrep is a code search agent that uses a multi-turn conversation to explore repositories. The model has its tools (grep_search, read, list_directory, glob, finish) built in — you do not need to pass a tools array in your requests.

Model

Use morph-warp-grep-v2.1 as the model identifier.

Message Format

WarpGrep uses a structured format in the initial user message with flat absolute paths:

<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/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>

Format Components

<repo_structure>: Flat list of absolute paths — repo root first, then all files/directories to depth 2. No indentation, no tree characters, no trailing / on directories.
<search_string>: Natural language description of what code to find

Example Request

import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: "YOUR_API_KEY",
  baseURL: "https://api.morphllm.com/v1",
});

const repoRoot = "/home/user/myapp";
const repoStructure = `${repoRoot}
${repoRoot}/src
${repoRoot}/src/auth
${repoRoot}/src/api
${repoRoot}/src/models
${repoRoot}/tests
${repoRoot}/package.json`;

const searchQuery = "Find where JWT tokens are validated";

const response = await openai.chat.completions.create({
  model: "morph-warp-grep-v2.1",
  messages: [
    {
      role: "user",
      content: `<repo_structure>\n${repoStructure}\n</repo_structure>\n\n<search_string>\n${searchQuery}\n</search_string>`
    }
  ],
  temperature: 0.0,
  max_tokens: 2048
});

// Response has tool_calls — execute locally and continue the loop
const toolCalls = response.choices[0].message.tool_calls;

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.morphllm.com/v1"
)

repo_root = "/home/user/myapp"
repo_structure = f"""{repo_root}
{repo_root}/src
{repo_root}/src/auth
{repo_root}/src/api
{repo_root}/src/models
{repo_root}/tests
{repo_root}/package.json"""

search_query = "Find where JWT tokens are validated"

response = client.chat.completions.create(
    model="morph-warp-grep-v2.1",
    messages=[
        {
            "role": "user",
            "content": f"<repo_structure>\n{repo_structure}\n</repo_structure>\n\n<search_string>\n{search_query}\n</search_string>"
        }
    ],
    temperature=0.0,
    max_tokens=2048,
)

# Response has tool_calls — execute locally and continue the loop
tool_calls = response.choices[0].message.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/home/user/myapp\n/home/user/myapp/src\n/home/user/myapp/src/auth\n</repo_structure>\n\n<search_string>\nFind where JWT tokens are validated\n</search_string>"
      }
    ],
    "temperature": 0.0,
    "max_tokens": 2048
  }'

See Direct API Access for the full protocol details including tool execution and multi-turn flow.

Multi-Turn Conversation

WarpGrep uses built-in tool calling (up to 6 turns). The agent will:

Turn 1: Analyze your search query and call tools (grep_search, list_directory, glob) to explore
Turns 2-5: Refine search based on results, read specific files
Final turn: Call finish with code locations

You execute tool calls locally and return results as {role: "tool", tool_call_id: "...", content: "..."} messages.

Request Parameters

Parameter	Type	Required	Description
`model`	string	Yes	Must be `morph-warp-grep-v2.1`
`messages`	array	Yes	Array of conversation messages
`temperature`	number	No	Recommended: `0.0` for deterministic results
`max_tokens`	number	No	Recommended: `2048`

Tools are built into the model — you do not need to pass a tools parameter. The model will return tool_calls automatically.

Response Format

The agent responds with structured tool_calls:

{
  "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\": \"jwt|JWT\"}"}},
        {"id": "chatcmpl-tool-def456", "type": "function", "function": {"name": "list_directory", "arguments": "{\"command\": \"ls src/auth\"}"}}
      ]
    },
    "finish_reason": "tool_calls"
  }],
  "usage": {
    "prompt_tokens": 1180,
    "total_tokens": 1245,
    "completion_tokens": 65
  }
}

After you execute tools and return results, the agent continues until it calls finish.

On tool-call turns the assistant content is null. Read only the tool_calls array.

Available Tools

WarpGrep uses five tools:

grep_search: Search for regex patterns across files. Case-insensitive by default.
read: Read file contents with optional line ranges
list_directory: Explore directory structure
glob: Find files by name/extension pattern (sorted by mtime)
finish: Submit final answer with code locations. Paths are absolute, matching the paths from the repo structure.

See the Direct API Guide for complete tool specifications.

Implement your tools to tolerate loose argument types. The model may send limit or case_sensitive as strings ("50", "false"), and grep_search may emit undocumented arguments such as output_lines (an alias for limit) or output_context_lines. Coerce known keys and ignore unrecognized ones rather than erroring. See the Direct API Guide for the full schema and robustness rules.

SDK Integration

For easier integration, use the WarpGrep SDK components:

TypeScript Tool: Drop-in tool for AI SDKs
Python Guide: Complete Python implementation

Error Codes

Direct API Guide

Build your own WarpGrep harness

Python Implementation

Complete Python guide with examples

Get Started

Models

API Reference

Integrations

Overview

Model

Message Format

Format Components

Example Request

Multi-Turn Conversation

Request Parameters

Response Format

Available Tools

SDK Integration

Error Codes

Direct API Guide

Python Implementation

​Overview

​Model

​Message Format

​Format Components

​Example Request

​Multi-Turn Conversation

​Request Parameters

​Response Format

​Available Tools

​SDK Integration

​Error Codes

Direct API Guide

Python Implementation

Overview

Model

Message Format

Format Components

Example Request

Multi-Turn Conversation

Request Parameters

Response Format

Available Tools

SDK Integration

Error Codes