Files API

File search and operations for OpenCode projects

Overview

The Files API provides file search capabilities within OpenCode projects, allowing you to quickly find files by name.

Search Files

Search for files in the project by name pattern.

GET /api/opencode/:port/files/search?q=<query>

Path Parameters

port · number · required

The OpenCode instance port number

Query Parameters

q · string · required

Search query string to match against file names

Response

files · array

Array of file path strings matching the query

Example

curl "http://localhost:3000/api/opencode/3100/files/search?q=api"

Response

[
  "src/api/users.ts",
  "src/api/auth.ts",
  "src/api/posts.ts",
  "tests/api/users.test.ts",
  "docs/api-reference.md"
]

Empty Query

If no query is provided or the query is empty, an empty array is returned:

curl "http://localhost:3000/api/opencode/3100/files/search"

Response

[]

---

Search Patterns

Exact Match

Search for exact filename matches:

curl "http://localhost:3000/api/opencode/3100/files/search?q=config.ts"

Partial Match

Search for files containing a substring:

curl "http://localhost:3000/api/opencode/3100/files/search?q=test"

Will match: test.ts, user.test.ts, testing-utils.ts, etc.

Extension Search

Search by file extension:

curl "http://localhost:3000/api/opencode/3100/files/search?q=.tsx"

Directory Path

Search including directory names:

curl "http://localhost:3000/api/opencode/3100/files/search?q=components/"

---

Use Cases

Quick File Navigation

async function findFile(filename) {
  const response = await fetch(
    `http://localhost:3000/api/opencode/3100/files/search?q=${encodeURIComponent(filename)}`
  );
  const files = await response.json();
  return files[0]; // Return first match
}

const userFile = await findFile('users.ts');
console.log('Found:', userFile);

Build Tool Integration

Find all test files:

const response = await fetch(
  'http://localhost:3000/api/opencode/3100/files/search?q=.test.ts'
);
const testFiles = await response.json();

console.log(`Found ${testFiles.length} test files`);
testFiles.forEach(file => console.log(`  - ${file}`));

IDE Integration

Implement fuzzy file search:

import requests
from urllib.parse import quote

def search_files(port, query):
    url = f'http://localhost:3000/api/opencode/{port}/files/search'
    response = requests.get(url, params={'q': query})
    return response.json()

# Search for TypeScript files
ts_files = search_files(3100, '.ts')
print(f"Found {len(ts_files)} TypeScript files")

---

Error Responses

Invalid Port

{
  "statusCode": 500,
  "message": "Invalid port"
}

---

Notes

The search is performed by the OpenCode instance’s file indexing system, which maintains a fast searchable index of all project files.

Search results are case-sensitive and match against the full file path relative to the project root.

For better performance with large projects, use more specific search queries to narrow down results.

The search query must be URL-encoded when passed as a query parameter. Special characters should be properly encoded.

URL Encoding Examples

# Space in query
curl "http://localhost:3000/api/opencode/3100/files/search?q=my%20file"

# Special characters
curl "http://localhost:3000/api/opencode/3100/files/search?q=file%2Bname"