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

Documentation Index

Fetch the complete documentation index at: https://docs.gentility.ai/llms.txt

Use this file to discover all available pages before exploring further.

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