WarpGrep API

POST

chat

completions

Create a chat completion

curl --request POST \
  --url https://api.morphllm.com/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "model": "morph-v3-fast",
  "messages": [
    {
      "role": "user",
      "content": "<instruction>I will add error handling</instruction>\n<code>function divide(a, b) {\n  return a / b;\n}</code>\n<update>function divide(a, b) {\n  if (b === 0) throw new Error('Division by zero');\n  return a / b;\n}</update>"
    }
  ],
  "stream": false,
  "max_tokens": 150,
  "temperature": 0
}
EOF

import requests

url = "https://api.morphllm.com/v1/chat/completions"

payload = {
    "model": "morph-v3-fast",
    "messages": [
        {
            "role": "user",
            "content": "<instruction>I will add error handling</instruction>
<code>function divide(a, b) {
  return a / b;
}</code>
<update>function divide(a, b) {
  if (b === 0) throw new Error('Division by zero');
  return a / b;
}</update>"
        }
    ],
    "stream": False,
    "max_tokens": 150,
    "temperature": 0
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'morph-v3-fast',
    messages: [
      {
        role: 'user',
        content: '<instruction>I will add error handling</instruction>\n<code>function divide(a, b) {\n  return a / b;\n}</code>\n<update>function divide(a, b) {\n  if (b === 0) throw new Error(\'Division by zero\');\n  return a / b;\n}</update>'
      }
    ],
    stream: false,
    max_tokens: 150,
    temperature: 0
  })
};

fetch('https://api.morphllm.com/v1/chat/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.morphllm.com/v1/chat/completions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'morph-v3-fast',
    'messages' => [
        [
                'role' => 'user',
                'content' => '<instruction>I will add error handling</instruction>
<code>function divide(a, b) {
  return a / b;
}</code>
<update>function divide(a, b) {
  if (b === 0) throw new Error(\'Division by zero\');
  return a / b;
}</update>'
        ]
    ],
    'stream' => false,
    'max_tokens' => 150,
    'temperature' => 0
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.morphllm.com/v1/chat/completions"

	payload := strings.NewReader("{\n  \"model\": \"morph-v3-fast\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"<instruction>I will add error handling</instruction>\\n<code>function divide(a, b) {\\n  return a / b;\\n}</code>\\n<update>function divide(a, b) {\\n  if (b === 0) throw new Error('Division by zero');\\n  return a / b;\\n}</update>\"\n    }\n  ],\n  \"stream\": false,\n  \"max_tokens\": 150,\n  \"temperature\": 0\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.morphllm.com/v1/chat/completions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"morph-v3-fast\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"<instruction>I will add error handling</instruction>\\n<code>function divide(a, b) {\\n  return a / b;\\n}</code>\\n<update>function divide(a, b) {\\n  if (b === 0) throw new Error('Division by zero');\\n  return a / b;\\n}</update>\"\n    }\n  ],\n  \"stream\": false,\n  \"max_tokens\": 150,\n  \"temperature\": 0\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.morphllm.com/v1/chat/completions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"morph-v3-fast\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"<instruction>I will add error handling</instruction>\\n<code>function divide(a, b) {\\n  return a / b;\\n}</code>\\n<update>function divide(a, b) {\\n  if (b === 0) throw new Error('Division by zero');\\n  return a / b;\\n}</update>\"\n    }\n  ],\n  \"stream\": false,\n  \"max_tokens\": 150,\n  \"temperature\": 0\n}"

response = http.request(request)
puts response.read_body

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "\ndef calculate_total(items):\n    total = 0\n    for item in items:\n        total += item.price\n    return total * 1.1  # Add 10% tax\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 32,
    "total_tokens": 57
  }
}

{
  "error": {
    "code": "invalid_request_error",
    "message": "The request body is missing the `model` field."
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided."
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry in 12 seconds."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side."
  }
}

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

Authorizations

Authorization

string

header

required

Morph API key, passed as Authorization: Bearer sk-.... Create keys at https://www.morphllm.com/dashboard/api-keys.

Body

application/json

Chat completion request for Apply or Warp Grep (OpenAI-compatible)

Morph Apply
Warp Grep

Either a Morph Apply request or a Warp Grep request, discriminated by model.

model

enum<string>

default:morph-v3-fast

required

ID of the Apply model to use, or auto to let the router choose

Available options:

morph-v3-fast,

morph-v3-large,

auto

Example:

"morph-v3-fast"

messages

object[]

required

Array containing a single user message with structured content using instruction-guided format

Show child attributes

Example:

[
  {
    "role": "user",
    "content": "<instruction>I will add error handling</instruction>\n<code>function divide(a, b) {\n  return a / b;\n}</code>\n<update>function divide(a, b) {\n  if (b === 0) throw new Error('Division by zero');\n  return a / b;\n}</update>"
  }
]

stream

boolean

default:false

Enable streaming response. When true the response is a text/event-stream of OpenAI-style chat.completion.chunk deltas terminated by data: [DONE].

Example:

false

max_tokens

integer

Maximum number of tokens the Apply model may generate

Example:

150

temperature

number

default:0

Sampling temperature for the Apply request (0.0 for deterministic output)

Example:

0

Response

Chat completion response

Completion returned by a Morph chat model.

string

required

Unique identifier for the completion

Example:

"chatcmpl-123"

object

string

required

Always chat.completion

Example:

"chat.completion"

created

integer

required

Unix timestamp of when the completion was created

Example:

1677652288

choices

object[]

required

List of completion choices

Show child attributes

Example:

[
  {
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "\ndef calculate_total(items):\n    total = 0\n    for item in items:\n        total += item.price\n    return total * 1.1  # Add 10% tax\n"
    },
    "finish_reason": "stop"
  }
]

usage

object

required

Usage statistics for the completion request

Show child attributes

Example:

{
  "prompt_tokens": 25,
  "completion_tokens": 32,
  "total_tokens": 57
}

Create a chat completion

curl --request POST \
  --url https://api.morphllm.com/v1/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "model": "morph-v3-fast",
  "messages": [
    {
      "role": "user",
      "content": "<instruction>I will add error handling</instruction>\n<code>function divide(a, b) {\n  return a / b;\n}</code>\n<update>function divide(a, b) {\n  if (b === 0) throw new Error('Division by zero');\n  return a / b;\n}</update>"
    }
  ],
  "stream": false,
  "max_tokens": 150,
  "temperature": 0
}
EOF

import requests

url = "https://api.morphllm.com/v1/chat/completions"

payload = {
    "model": "morph-v3-fast",
    "messages": [
        {
            "role": "user",
            "content": "<instruction>I will add error handling</instruction>
<code>function divide(a, b) {
  return a / b;
}</code>
<update>function divide(a, b) {
  if (b === 0) throw new Error('Division by zero');
  return a / b;
}</update>"
        }
    ],
    "stream": False,
    "max_tokens": 150,
    "temperature": 0
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'morph-v3-fast',
    messages: [
      {
        role: 'user',
        content: '<instruction>I will add error handling</instruction>\n<code>function divide(a, b) {\n  return a / b;\n}</code>\n<update>function divide(a, b) {\n  if (b === 0) throw new Error(\'Division by zero\');\n  return a / b;\n}</update>'
      }
    ],
    stream: false,
    max_tokens: 150,
    temperature: 0
  })
};

fetch('https://api.morphllm.com/v1/chat/completions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.morphllm.com/v1/chat/completions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'morph-v3-fast',
    'messages' => [
        [
                'role' => 'user',
                'content' => '<instruction>I will add error handling</instruction>
<code>function divide(a, b) {
  return a / b;
}</code>
<update>function divide(a, b) {
  if (b === 0) throw new Error(\'Division by zero\');
  return a / b;
}</update>'
        ]
    ],
    'stream' => false,
    'max_tokens' => 150,
    'temperature' => 0
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.morphllm.com/v1/chat/completions"

	payload := strings.NewReader("{\n  \"model\": \"morph-v3-fast\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"<instruction>I will add error handling</instruction>\\n<code>function divide(a, b) {\\n  return a / b;\\n}</code>\\n<update>function divide(a, b) {\\n  if (b === 0) throw new Error('Division by zero');\\n  return a / b;\\n}</update>\"\n    }\n  ],\n  \"stream\": false,\n  \"max_tokens\": 150,\n  \"temperature\": 0\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.morphllm.com/v1/chat/completions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"morph-v3-fast\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"<instruction>I will add error handling</instruction>\\n<code>function divide(a, b) {\\n  return a / b;\\n}</code>\\n<update>function divide(a, b) {\\n  if (b === 0) throw new Error('Division by zero');\\n  return a / b;\\n}</update>\"\n    }\n  ],\n  \"stream\": false,\n  \"max_tokens\": 150,\n  \"temperature\": 0\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.morphllm.com/v1/chat/completions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"morph-v3-fast\",\n  \"messages\": [\n    {\n      \"role\": \"user\",\n      \"content\": \"<instruction>I will add error handling</instruction>\\n<code>function divide(a, b) {\\n  return a / b;\\n}</code>\\n<update>function divide(a, b) {\\n  if (b === 0) throw new Error('Division by zero');\\n  return a / b;\\n}</update>\"\n    }\n  ],\n  \"stream\": false,\n  \"max_tokens\": 150,\n  \"temperature\": 0\n}"

response = http.request(request)
puts response.read_body

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "\ndef calculate_total(items):\n    total = 0\n    for item in items:\n        total += item.price\n    return total * 1.1  # Add 10% tax\n"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 32,
    "total_tokens": 57
  }
}

{
  "error": {
    "code": "invalid_request_error",
    "message": "The request body is missing the `model` field."
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided."
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry in 12 seconds."
  }
}

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong on our side."
  }
}

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

Authorizations

Body

Response

​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

Authorizations

Body

Response

Overview

Model

Message Format

Format Components

Example Request

Multi-Turn Conversation

Request Parameters

Response Format

Available Tools

SDK Integration

Error Codes