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

Warp Grep is an AI-powered code search agent that intelligently navigates codebases to find relevant code. It uses a multi-turn conversation pattern where the agent calls tools (grep, read, list_directory, finish) to explore your repository and return precise code locations.

​
Model

Use morph-warp-grep-v1 as the model identifier. This model is specifically trained to understand code structure and make intelligent search decisions.

​
Message Format

Warp Grep uses a structured XML format in the initial user message: 
<repo_structure>
myproject/
  src/
    auth/
    db/
    utils/
  tests/
  config.py
  main.py
  README.md
</repo_structure>

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

​
Format Components

  • <repo_structure>: Directory tree of your repository (typically root with depth 2)
  • <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 repoStructure = `myapp/
  src/
    auth/
    api/
    models/
  tests/
  package.json`;

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

const response = await openai.chat.completions.create({
  model: "morph-warp-grep-v1",
  messages: [
    {
      role: "system",
      content: "You are a code search agent. Use grep/read/list_directory/finish to locate code."
    },
    {
      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
});

​
Multi-Turn Conversation

Warp Grep uses a multi-turn conversation pattern (up to 4 turns). The agent will:
  1. Turn 1: Analyze your search query and call tools (grep, list_directory) to explore
  2. Turns 2-3: Refine search based on results
  3. Turn 4: Call finish with final code locations
You execute the tool calls locally and return results in XML format. See the Direct API Guide for complete protocol details.

​
Request Parameters

ParameterTypeRequiredDescription
modelstringYesMust be morph-warp-grep-v1
messagesarrayYesArray with system and user messages
temperaturenumberNoRecommended: 0.0 for deterministic results
max_tokensnumberNoRecommended: 2048 (default)

​
Response Format

The agent responds with tool calls in XML format: 
<think>
Looking for JWT validation. I'll grep for jwt-related patterns
and check the auth directory.
</think>

<grep>
  <pattern>jwt|JWT</pattern>
  <sub_dir>src/</sub_dir>
</grep>

<list_directory>
  <path>src/auth</path>
</list_directory>
After you execute tools and return results, the agent will continue until it calls finish: 
<finish>
  <file>
    <path>src/auth/jwt.ts</path>
    <lines>1-60</lines>
  </file>
  <file>
    <path>src/middleware/auth.ts</path>
    <lines>1-40</lines>
  </file>
</finish>

​
Available Tools

Warp Grep uses four tools:
  • grep: Search for regex patterns across files
  • read: Read file contents with optional line ranges
  • list_directory: Show directory structure
  • finish: Submit final answer with code locations
See the Direct API Guide for complete tool specifications and execution details.

​
SDK Integration

For easier integration, use the Warp Grep SDK components:

​
Error Codes

Direct API Guide

Build your own Warp Grep 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