> ## Documentation Index
> Fetch the complete documentation index at: https://docs.relace.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Search Code
> Run the Fast Agentic Search model (`relace-search`) one turn at a time through an OpenAI-compatible chat completions request. You supply the agent harness: the search tools and the code that executes them.
Relace Search is the model behind [Fast Agentic Search](/docs/fast-agentic-search/agent). It explores a codebase in 4-5 turns of parallel tool calls and reports back the relevant files with line ranges.
This endpoint runs the model one turn at a time. You own the agent loop: send the conversation so far, execute the tool calls it returns against your codebase, append the results, and call again until it calls `report_back`.
If your code lives in a [Relace Repo](/docs/repos/overview), use the [Fast Agentic Search](/api-reference/agents/fast-agentic-search) endpoint instead. It runs the full loop on our infrastructure and streams the result back.
## Models
| Model | Tools |
| :-------------- | :------------------------------------------------------------------ |
| `relace-search` | `view_file`, `view_directory`, `grep_search`, `bash`, `report_back` |
## OpenAI SDK
Point an OpenAI client at the `/v1/search` base URL. The model is also reachable as `relace-search` on the shared [`/v1/chat/completions`](/api-reference/open-models/chat-completions) route.
```typescript theme={null}
import OpenAI from 'openai';
const client = new OpenAI({
apiKey: 'YOUR_API_KEY',
baseURL: 'https://models.relace.ai/v1/search',
});
const response = await client.chat.completions.create({
model: 'relace-search',
messages: [
{ role: 'system', content: systemPrompt },
{ role: 'user', content: userPrompt },
],
tools: searchTools,
tool_choice: 'auto',
});
```
The model is trained against the exact system prompt, user prompt template, and tool schemas in the [agent harness guide](/docs/fast-agentic-search/agent). Deviating from them degrades search quality.
## OpenAPI
````yaml POST /v1/search/chat/completions
openapi: 3.0.1
info:
title: Relace API
description: API for accessing Relace code generation models.
version: 1.0.0
license:
name: MIT
servers:
- url: https://models.relace.ai
description: Server for model API endpoints
- url: https://api.relace.run
description: Server for general infrastructure
security:
- bearerAuth: []
paths:
/v1/search/chat/completions:
post:
description: >-
Run the Fast Agentic Search model (`relace-search`) one turn at a time
through an OpenAI-compatible chat completions request. You supply the
agent harness: the search tools and the code that executes them.
requestBody:
description: >-
OpenAI-compatible chat completions request with the Fast Agentic
Search tool definitions
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchChatCompletionsRequest'
example:
model: relace-search
messages:
- role: system
content: >-
You are an AI agent whose job is to explore a code base with
the provided tools and thoroughly understand the problem.
...
- role: user
content: |-
I have uploaded a code repository in the /repo directory.
Now consider the following user query:
How is user authentication handled in this codebase?
...
tools:
- type: function
function:
name: view_file
description: Tool for viewing/exploring the contents of existing files
parameters:
type: object
required:
- path
- view_range
properties:
path:
type: string
view_range:
type: array
items:
type: integer
- type: function
function:
name: report_back
description: Report the relevant files once the codebase is understood
parameters:
type: object
required:
- explanation
- files
properties:
explanation:
type: string
files:
type: object
tool_choice: auto
stream: false
responses:
'200':
description: Chat completion generated
content:
application/json:
schema:
$ref: '#/components/schemas/ChatCompletionsResponse'
text/event-stream:
schema:
type: string
description: >-
Stream of chat completion chunks in the OpenAI streaming
format. Token usage is reported in the final chunk.
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'402':
description: Out of credits, or no payment method on the account
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'404':
description: Route not found
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'429':
description: Rate limit exceeded, or the model is at capacity
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'502':
description: Model server error
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'503':
description: Model temporarily unavailable
headers:
Retry-After:
schema:
type: string
description: Seconds to wait before retrying
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
'504':
description: Request to the model timed out
content:
application/json:
schema:
$ref: '#/components/schemas/OpenAIError'
servers:
- url: https://models.relace.ai
components:
schemas:
SearchChatCompletionsRequest:
type: object
required:
- model
- messages
properties:
model:
type: string
description: >-
Must be `relace-search`. This route serves only the Fast Agentic
Search model.
messages:
type: array
items:
type: object
description: >-
The agent conversation so far, as OpenAI-format message objects: the
system prompt, the user prompt, and any previous `assistant` tool
calls with their `tool` results.
tools:
type: array
items:
type: object
description: >-
OpenAI-format function tool definitions. Use the exact `view_file`,
`view_directory`, `grep_search`, `bash`, and `report_back` schemas
from the [agent harness
guide](/docs/fast-agentic-search/agent#tool-schema-definition); the
model is trained against them.
tool_choice:
description: >-
Controls tool use: `none`, `auto`, `required`, or a specific tool.
Use `auto`.
stream:
type: boolean
description: >-
If true, tokens are sent as server-sent events as they are
generated. Token usage is always reported in the final chunk of the
stream.
max_tokens:
type: integer
description: Maximum number of tokens to generate for this turn.
stop:
type: array
items:
type: string
description: Sequences at which generation stops.
seed:
type: integer
description: Seed for deterministic sampling where supported.
description: >-
OpenAI-compatible request for one turn of the search agent. Fields
outside this list are ignored.
ChatCompletionsResponse:
type: object
properties:
id:
type: string
description: Unique identifier for the completion
object:
type: string
description: Always `chat.completion`
created:
type: integer
description: Unix timestamp of when the completion was created
model:
type: string
description: The model that served the request
choices:
type: array
items:
type: object
properties:
index:
type: integer
message:
type: object
description: >-
The generated message, with `role` and `content` (and
`tool_calls` when the model called tools)
finish_reason:
type: string
description: Why generation stopped, e.g. `stop`, `length`, or `tool_calls`
description: The generated completions
usage:
type: object
properties:
prompt_tokens:
type: integer
description: Number of tokens in the prompt
completion_tokens:
type: integer
description: Number of tokens in the completion
total_tokens:
type: integer
description: Total number of tokens used
description: Token usage information for the request
OpenAIError:
type: object
properties:
error:
type: object
properties:
message:
type: string
description: Error message
example: >-
Rate limit exceeded. Retry after the Retry-After interval, or
contact support to raise your limits.
type:
type: string
description: OpenAI error type
enum:
- invalid_request_error
- authentication_error
- insufficient_quota
- rate_limit_error
- api_error
example: rate_limit_error
param:
type: string
nullable: true
description: Offending request parameter, when known
example: null
code:
type: string
nullable: true
description: Always null on Relace-authored errors
example: null
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Relace API key Authorization header using the Bearer scheme.
````