# Agent: Files

**Page:** api/agent/files

[Download Raw Markdown](./api/agent/files.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The Agent Files API provides workspace-scoped access to file and search operations. Use these endpoints to list directories, read file contents, check git status, and perform name, text, or symbol searches across a workspace.

All endpoints are scoped to a workspace via the `{workspaceID}` path parameter.

## List files

Returns the files and directories at a given path within a workspace.

`GET /api/v1/workspaces/{workspaceID}/files/file`

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `path` | query | string | Yes | The directory path to list, relative to the workspace root |

### Response (200)

Returns an array of `agent_FileNode` objects describing each entry at the requested path.

```json
[
  {
    "name": "index.ts",
    "path": "src/index.ts",
    "absolute": "/home/user/project/src/index.ts",
    "type": "file",
    "ignored": false
  },
  {
    "name": "utils",
    "path": "src/utils",
    "absolute": "/home/user/project/src/utils",
    "type": "directory",
    "ignored": false
  }
]
```

**FileNode fields**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | The file or directory name |
| `path` | string | Yes | The path relative to the workspace root |
| `absolute` | string | Yes | The absolute path on disk |
| `type` | string | Yes | One of `"file"`, `"directory"` |
| `ignored` | boolean | Yes | Whether the entry is matched by ignore rules |

### Example request




```bash
curl -X GET "https://api.hoody.com/v1/workspaces/ws_abc123/files/file?path=src" \
  -H "Authorization: Bearer <token>"
```




```ts
const files = await client.agent.files.list({
  workspaceID: "ws_abc123",
  path: "src"
});
```




## Read file

Reads the content of a file, returning text, a unified diff, or base64-encoded binary data.

`GET /api/v1/workspaces/{workspaceID}/files/file/content`

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `path` | query | string | Yes | The file path, relative to the workspace root |

### Response (200)

Returns an `agent_FileContent` object.

```json
{
  "type": "text",
  "content": "export function hello() {\n  return 'world';\n}\n",
  "diff": "@@ -1,3 +1,3 @@\n export function hello() {\n-  return 'hello';\n+  return 'world';\n }\n",
  "patch": {
    "oldFileName": "src/index.ts",
    "newFileName": "src/index.ts",
    "oldHeader": "a/src/index.ts",
    "newHeader": "b/src/index.ts",
    "hunks": [
      {
        "oldStart": 1,
        "oldLines": 3,
        "newStart": 1,
        "newLines": 3,
        "lines": [
          " export function hello() {",
          "-  return 'hello';",
          "+  return 'world';",
          " }"
        ]
      }
    ],
    "index": "abc1234"
  },
  "encoding": "base64",
  "mimeType": "text/typescript"
}
```

**FileContent fields**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `type` | string | Yes | One of `"text"`, `"binary"` |
| `content` | string | Yes | The file content (text or base64-encoded) |
| `diff` | string | No | A unified diff representing changes |
| `patch` | object | No | Structured patch data with old/new file names and hunks |
| `encoding` | string | No | Always `"base64"` when the file is binary |
| `mimeType` | string | No | The detected MIME type of the file |

### Example request




```bash
curl -X GET "https://api.hoody.com/v1/workspaces/ws_abc123/files/file/content?path=src/index.ts" \
  -H "Authorization: Bearer <token>"
```




```ts
const file = await client.agent.files.readContent({
  workspaceID: "ws_abc123",
  path: "src/index.ts"
});
```




## Get file status

Returns the git status of all files in the project, including added, removed, and modified line counts.

`GET /api/v1/workspaces/{workspaceID}/files/file/status`

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |

### Response (200)

Returns an array of `agent_File` objects.

```json
[
  {
    "path": "src/index.ts",
    "added": 5,
    "removed": 2,
    "status": "modified"
  },
  {
    "path": "src/new-file.ts",
    "added": 20,
    "removed": 0,
    "status": "added"
  },
  {
    "path": "src/old-file.ts",
    "added": 0,
    "removed": 45,
    "status": "deleted"
  }
]
```

**File fields**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | string | Yes | The file path relative to the workspace root |
| `added` | integer | Yes | Number of lines added |
| `removed` | integer | Yes | Number of lines removed |
| `status` | string | Yes | One of `"added"`, `"deleted"`, `"modified"` |

### Example request




```bash
curl -X GET "https://api.hoody.com/v1/workspaces/ws_abc123/files/file/status" \
  -H "Authorization: Bearer <token>"
```




```ts
const status = await client.agent.files.getStatus({
  workspaceID: "ws_abc123"
});
```




## Find text

Searches for a text pattern across files using ripgrep. Returns matching lines with file path, line number, and submatch positions.

`GET /api/v1/workspaces/{workspaceID}/files/find`

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `pattern` | query | string | Yes | The ripgrep pattern to search for |

### Response (200)

Returns an array of match objects.

```json
[
  {
    "path": {
      "text": "src/utils/helpers.ts"
    },
    "lines": {
      "text": "export function formatDate(date: Date) {"
    },
    "line_number": 12,
    "absolute_offset": 345,
    "submatches": [
      {
        "match": {
          "text": "formatDate"
        },
        "start": 17,
        "end": 27
      }
    ]
  }
]
```

**Match fields**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `path` | object | Yes | Object containing the matching file's `text` path |
| `lines` | object | Yes | Object containing the full matching line's `text` |
| `line_number` | number | Yes | The 1-based line number of the match |
| `absolute_offset` | number | Yes | The absolute byte offset of the match in the file |
| `submatches` | array | Yes | Individual submatch ranges within the line |

### Example request




```bash
curl -X GET "https://api.hoody.com/v1/workspaces/ws_abc123/files/find?pattern=formatDate" \
  -H "Authorization: Bearer <token>"
```




```ts
const matches = await client.agent.files.search({
  workspaceID: "ws_abc123",
  pattern: "formatDate"
});
```




## Find files

Searches for files or directories by name or glob pattern within a workspace.

`GET /api/v1/workspaces/{workspaceID}/files/find/file`

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `query` | query | string | Yes | The name or glob pattern to match |
| `dirs` | query | string | No | Restrict results to directories. Allowed values: `"true"`, `"false"` |
| `type` | query | string | No | Restrict the result type. Allowed values: `"file"`, `"directory"` |
| `limit` | query | integer | No | Maximum number of results to return |

### Response (200)

Returns an array of file path strings.

```json
[
  "src/index.ts",
  "src/utils/index.ts",
  "tests/index.test.ts"
]
```

### Example request




```bash
curl -X GET "https://api.hoody.com/v1/workspaces/ws_abc123/files/find/file?query=index.ts" \
  -H "Authorization: Bearer <token>"
```




```ts
const paths = await client.agent.files.findByName({
  workspaceID: "ws_abc123",
  query: "index.ts"
});
```




## Find symbols

Searches for workspace symbols — functions, classes, variables, and other language constructs — using LSP.

`GET /api/v1/workspaces/{workspaceID}/files/find/symbol`

### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier |
| `query` | query | string | Yes | The symbol name or query string to search for |

### Response (200)

Returns an array of `agent_Symbol` objects.

```json
[
  {
    "name": "formatDate",
    "kind": 12,
    "location": {
      "uri": "file:///src/utils/helpers.ts",
      "range": {
        "start": {
          "line": 11,
          "character": 0
        },
        "end": {
          "line": 13,
          "character": 1
        }
      }
    }
  }
]
```

**Symbol fields**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | The symbol name |
| `kind` | number | Yes | The LSP symbol kind code |
| `location` | object | Yes | The symbol's source location, with a `uri` and `range` |

### Example request




```bash
curl -X GET "https://api.hoody.com/v1/workspaces/ws_abc123/files/find/symbol?query=formatDate" \
  -H "Authorization: Bearer <token>"
```




```ts
const symbols = await client.agent.files.findSymbols({
  workspaceID: "ws_abc123",
  query: "formatDate"
});
```