Skip to main content
POST
/
v1
/
chat
/
completions
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>"
    }
  ],
  "temperature": 0
}
EOF
{
  "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
  }
}

​
Overview

WarpGrep is a code search agent that uses a multi-turn conversation with OpenAI-compatible tool calling to explore repositories via grep_search, read, list_directory, glob, and finish tools.

​
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>`
    }
  ],
  tools: [
    { type: "function", function: { name: "grep_search", parameters: { type: "object", properties: { pattern: { type: "string" }, path: { type: "string" }, glob: { type: "string" }, limit: { type: "integer" } }, required: ["pattern"] } } },
    { type: "function", function: { name: "read", parameters: { type: "object", properties: { path: { type: "string" }, lines: { type: "string" } }, required: ["path"] } } },
    { type: "function", function: { name: "list_directory", parameters: { type: "object", properties: { command: { type: "string" } }, required: ["command"] } } },
    { type: "function", function: { name: "glob", parameters: { type: "object", properties: { pattern: { type: "string" }, path: { type: "string" } }, required: ["pattern"] } } },
    { type: "function", function: { name: "finish", parameters: { type: "object", properties: { files: { type: "string" } }, required: ["files"] } } },
  ],
  temperature: 0.0,
  max_tokens: 2048
});

// Response has tool_calls — execute locally and continue the loop
const toolCalls = response.choices[0].message.tool_calls;
See Direct API Access for the full protocol details including tool execution and multi-turn flow.

​
Multi-Turn Conversation

WarpGrep uses native OpenAI 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

ParameterTypeRequiredDescription
modelstringYesMust be morph-warp-grep-v2.1
messagesarrayYesArray of conversation messages
toolsarrayYesTool definitions (see Direct API guide)
temperaturenumberNoRecommended: 0.0 for deterministic results
max_tokensnumberNoRecommended: 2048

​
Response Format

The agent responds with structured tool_calls: 
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {"id": "call_abc", "type": "function", "function": {"name": "grep_search", "arguments": "{\"pattern\": \"jwt|JWT\"}"}},
        {"id": "call_def", "type": "function", "function": {"name": "list_directory", "arguments": "{\"command\": \"ls src/auth\"}"}}
      ]
    }
  }]
}
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 for complete tool specifications.

​
SDK Integration

For easier integration, use the WarpGrep SDK components:

​
Error Codes

Direct API Guide

Build your own WarpGrep harness

Python Implementation

Complete Python guide with examples

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

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

​
model
enum<string>
default:morph-v3-fast
required

ID of the model to use

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

​
stream
boolean
default:false

Enable streaming response

Example:

false

​
max_tokens
integer

Maximum number of tokens to generate

Example:

150

​
temperature
number
default:0

Sampling temperature (0.0 for deterministic output)

Example:

0

Response

Chat completion response

​
id
string
required

Unique identifier for the completion

Example:

"chatcmpl-123"

​
object
string
required

Object type

Example:

"chat.completion"

​
created
integer
required

Unix timestamp of when the completion was created

Example:

1677652288

​
choices
object[]
required

List of completion choices

​
usage
object
required

Usage statistics for the completion request