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>'
import requests

url = "https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/file/{path}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/file/{path}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/file/{path}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/file/{path}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/file/{path}")
  .header("Authorization", "Bearer <token>")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/file/{path}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
{
  "file_path": "<string>",
  "content": "<string>",
  "instance_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
{
  "error": "<string>",
  "message": "<string>"
}
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