Skip to main content
GET
/
api
/
profile
/
{profile_id}
/
room
/
{room_id}
/
file
/
{path}
Read file from VM instance
curl --request GET \
  --url https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/file/{path} \
  --header 'Authorization: Bearer <token>'
{
  "file_path": "<string>",
  "content": "<string>",
  "instance_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
Reads files from VM instances and returns their content as JSON. This endpoint supports reading any file within the VM filesystem that the user has access to.

​
Path Parameter

The {path} parameter is a wildcard that captures the full file path within the VM. For example:
  • /home/user/script.py
  • /tmp/output.json
  • /workspace/data/results.csv
  • /etc/hosts (if readable)

​
Use Cases

  • Result Retrieval: Read output files generated by executed commands
  • Configuration Access: Read configuration files and settings
  • Data Export: Access data files, logs, and generated reports
  • AI Agent File Access: Allow AI agents to read files they’ve created or need to analyze

​
Response Examples

​
Text File Content

{
  "file_path": "/home/user/script.py",
  "content": "#!/usr/bin/env python3\n\nprint('Hello, Gentility!')\n\n# This is a sample Python script\nfor i in range(5):\n    print(f'Count: {i}')",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
JSON File Content

{
  "file_path": "/tmp/analysis_results.json",
  "content": "{\n  \"summary\": \"Data analysis complete\",\n  \"total_records\": 1500,\n  \"insights\": [\n    \"Peak usage occurs at 3 PM\",\n    \"Weekend traffic is 40% lower\"\n  ]\n}",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
Binary File Handling

For binary files, the content will be base64 encoded: 
{
  "file_path": "/home/user/chart.png", 
  "content": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAABH...",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000"
}

​
File Not Found

{
  "error": "file_not_found",
  "message": "File '/nonexistent/path.txt' not found in instance"
}

​
Instance Not Found

{
  "error": "instance_not_found", 
  "message": "No instance found for profile 6ba7b810-9dad-11d1-80b4-00c04fd430c8 and room ai-session-123"
}

​
Alternative: Direct File Access

For unauthenticated access (useful for AI agents), you can also use the direct file access endpoint: 
GET /vm/{instance_id}/file/{path}
This endpoint:
  • Requires no authentication
  • Serves files with appropriate MIME types
  • Returns raw file content (not JSON wrapped)
  • Suitable for images, PDFs, and other binary files

​
Best Practices

  • File Paths: Use absolute paths starting from / or relative paths from the VM’s home directory
  • Large Files: Be mindful that very large files will be returned as base64 encoded strings
  • Security: Only files accessible to the VM user can be read
  • Caching: File content is read fresh on each request - no caching is performed
  • Error Handling: Always check for 404 errors when files might not exist

Authorizations

​
Authorization
string
header
required

API key authentication using Bearer token format: 'Bearer rk_live_'

Path Parameters

​
profile_id
string<uuid>
required

UUID of the profile

​
room_id
string
required

Room identifier

​
path
string
required

File path within the VM (wildcard path parameter)

Response

File content retrieved successfully

​
file_path
string
required

Path to the file within the VM

​
content
string
required

File content as string

​
instance_id
string<uuid>
required

Instance containing the file