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

# WarpGrep API

> Semantic code search subagent that explores repositories in ~6 seconds

## 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**:

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

<CodeGroup>
  ```typescript TypeScript theme={null}
  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;
  ```

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

  ```bash cURL theme={null}
  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
    }'
  ```
</CodeGroup>

<Note>See [Direct API Access](/sdk/components/warp-grep/direct) for the full protocol details including tool execution and multi-turn flow.</Note>

## Multi-Turn Conversation

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

1. **Turn 1**: Analyze your search query and call tools (`grep_search`, `list_directory`, `glob`) to explore
2. **Turns 2-5**: Refine search based on results, read specific files
3. **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`                          |

<Note>Tools are built into the model — you do **not** need to pass a `tools` parameter. The model will return `tool_calls` automatically.</Note>

## Response Format

The agent responds with structured `tool_calls`:

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "morph-warp-grep-v2.1",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "",
      "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`.

## Available Tools

WarpGrep uses five tools:

* **`grep_search`**: Search for regex patterns across files
* **`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

See the [Direct API Guide](/sdk/components/warp-grep/direct) for complete tool specifications.

## SDK Integration

For easier integration, use the WarpGrep SDK components:

* **[TypeScript Tool](/sdk/components/warp-grep/tool)**: Drop-in tool for AI SDKs
* **[Python Guide](/guides/warp-grep-python)**: Complete Python implementation

## Error Codes

<Table>
  <TableHead>
    <TableRow>
      <TableHeader>HTTP Status</TableHeader>
      <TableHeader>Description</TableHeader>
    </TableRow>
  </TableHead>

  <TableBody>
    <TableRow>
      <TableCell>
        <code>200</code>
      </TableCell>

      <TableCell>Success - chat completion response with tool\_calls</TableCell>
    </TableRow>

    <TableRow>
      <TableCell>
        <code>400</code>
      </TableCell>

      <TableCell>Bad request - malformed request or parameters</TableCell>
    </TableRow>

    <TableRow>
      <TableCell>
        <code>401</code>
      </TableCell>

      <TableCell>Authentication error - invalid API key</TableCell>
    </TableRow>
  </TableBody>
</Table>

<CardGroup cols={2}>
  <Card title="Direct API Guide" icon="code" href="/sdk/components/warp-grep/direct">
    Build your own WarpGrep harness
  </Card>

  <Card title="Python Implementation" icon="book" href="/guides/warp-grep-python">
    Complete Python guide with examples
  </Card>
</CardGroup>