Agent: Files

Download Page (.md)

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.

[
  {
    "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

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

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.

{
  "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

cURL
TypeScript SDK

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

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.

[
  {
    "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

cURL
TypeScript SDK

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

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.

[
  {
    "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

cURL
TypeScript SDK

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

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.

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

Example request

cURL
TypeScript SDK

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

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.

[
  {
    "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

cURL
TypeScript SDK

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

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