Skip to main content

​
Welcome to the Gentility AI API

Gentility AI provides instant, secure work environments for AI agents through a simple HTTP API. Our platform allows you to spin up isolated virtual machines, execute commands, access files, and provide your AI agents with the powerful tools they need to complete their tasks.

Gentility AI API Specification

View the complete OpenAPI specification

​
Key Features

  • Instant VM Provisioning: Spin up secure development environments in milliseconds
  • Multi-tenant Isolation: Organization-scoped access with room-based VM separation
  • Command Execution: Execute shell commands with real-time output and file change tracking
  • File Operations: Read and write files within VM instances
  • AI Tool Integration: Dynamic tool schema generation for AI agents
  • Profile Templates: Configurable VM environments with custom packages and settings

​
Authentication

All API endpoints require authentication using Bearer tokens with your API key: 
curl -H "Authorization: Bearer rk_live_your_api_key_here" \
  https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}

​
API Key Format

API keys follow the pattern: rk_{environment}_{32_hex_characters}
  • Production: rk_live_...
  • Development: rk_test_...
Keep your API keys secure and never expose them in client-side code or public repositories.

​
Core Concepts

​
Profiles

VM configuration templates that define:
  • Memory allocation and filesystem size
  • Base Docker image and kernel configuration
  • Installed packages and development tools
  • Organization-specific settings

​
Rooms

Logical isolation boundaries within profiles that allow multiple concurrent VM instances for different sessions or users.

​
Instances

Active virtual machines provisioned from profiles, progressing through states: active → network_allocated → ftap_created → image_generated → vm_started → vm_booted → ready

​
Multi-tenant Architecture

All operations are scoped to your organization, ensuring complete isolation between different customers and teams.

​
Quick Start

  1. Create a VM Instance 
    POST /api/profile/{profile_id}/room/{room_id}
  2. Execute Commands 
    POST /api/profile/{profile_id}/room/{room_id}/command
  3. Read Files 
    GET /api/profile/{profile_id}/room/{room_id}/file/{path}
  4. Get AI Tool Schema 
    GET /api/profile/{profile_id}/room/{room_id}/tools

​
Support

For questions, issues, or feature requests: