# TrueNAS API Documentation

> This site provides comprehensive API documentation for TrueNAS versions 24.10 and later. The documentation covers the versioned JSON-RPC 2.0 WebSocket API (introduced with TrueNAS 25.04) that allows programmatic interaction with TrueNAS middleware for automation, integration, and advanced system management.

## Quick Reference - Most Common Tasks

### Getting Started with TrueNAS API
1. **API Client Setup**: Install the TrueNAS API Client from https://github.com/truenas/api_client
2. **Local API Access**: Use `midclt` command-line tool for local system management
3. **Remote API Access**: Connect to remote TrueNAS instances via WebSocket
4. **Built-in Documentation**: Access live API docs at `https://your-truenas-ip/api/docs/`

### API Documentation Structure
- **Version-specific docs**: Each TrueNAS version has dedicated API documentation
- **WebSocket API**: JSON-RPC 2.0 protocol for real-time communication
- **Method Reference**: Complete list of available API calls and parameters
- **Response Examples**: Sample API responses and error handling

## Site Description

This is the official TrueNAS API documentation site (api.truenas.com), providing comprehensive reference documentation for the TrueNAS WebSocket API. The site is automatically generated from the TrueNAS middleware source code and covers all API endpoints, methods, parameters, and responses.

**Current Coverage**: TrueNAS 24.10 and later versions
**API Type**: Versioned JSON-RPC 2.0 WebSocket API
**Primary Use Cases**: System automation, integration development, advanced configuration management

## API Version Access

The site provides version-specific API documentation for multiple TrueNAS releases:

### Version URL Structure
- **URL Pattern**: `https://api.truenas.com/v{version}/`
- **Examples**: `api.truenas.com/v25.04.2/`, `api.truenas.com/v24.10/`, `api.truenas.com/v25.10.0/`
- **Version Discovery**: Check https://api.truenas.com/ for complete list of available versions

### Version Selection Guidance
- **For general queries**: Use the latest stable version (typically 25.04.x series)
- **For user-specified versions**: Match the TrueNAS version the user mentions
- **Coverage range**: Documentation available for TrueNAS 24.10 and later
- **Version compatibility**: API methods and events may vary between versions

### API Documentation Structure

Each version includes five main sections:
- **JSON-RPC 2.0 over WebSocket API**: Protocol details, request/response formats, event notifications
- **API Methods**: Complete method reference with parameters and examples
- **API Events**: Queryable events across all system domains (alerts, apps, certificates, etc.)
- **Jobs**: Job method calling, status querying, file upload/download processes
- **Query Methods**: Advanced filtering, operators, SQL-like query translation

## Key API Categories

### System Management APIs
- **System Configuration**: Global system settings and preferences
- **Service Management**: Start, stop, and configure system services
- **Update Management**: System updates and version management
- **Hardware Monitoring**: Disk, CPU, memory, and network statistics

### Storage Management APIs
- **Pool Management**: ZFS pool creation, configuration, and monitoring
- **Dataset Operations**: Dataset creation, snapshots, and clones
- **Disk Management**: Disk detection, testing, and replacement procedures
- **SMART Monitoring**: Drive health and predictive failure detection

### Data Sharing APIs
- **SMB/CIFS Shares**: Windows file sharing configuration
- **NFS Exports**: Unix/Linux file sharing setup
- **FTP Services**: File transfer protocol configuration
- **iSCSI Targets**: Block-level storage sharing

### Network Configuration APIs
- **Interface Management**: Network interface configuration
- **Routing Tables**: Static routes and gateway configuration
- **DNS Settings**: Name resolution and domain configuration
- **Firewall Rules**: Network security and access control

### User Management APIs
- **Local Users**: User account creation and modification
- **Groups**: User group management and permissions
- **Directory Services**: Active Directory and LDAP integration
- **Permissions**: File system and share access control

### Application APIs
- **App Management**: Docker container deployment and management
- **Service Configuration**: Application-specific settings
- **Resource Allocation**: CPU, memory, and storage limits
- **Network Configuration**: Container networking and port mapping

## Using the TrueNAS API

### API Client Installation

The official TrueNAS API Client provides the easiest way to interact with the API:

```bash
pip install truenas-api-client
```

### Command Line Usage

The `midclt` tool provides direct command-line access:

```bash
# Connect to local instance
midclt call system.info

# Connect to remote instance
midclt -h <truenas-host> -u <username> -p <password> call system.info
```

### WebSocket Connection

Direct WebSocket connection for custom applications:

```python
import websocket
import json

# Connect to TrueNAS WebSocket API
ws = websocket.WebSocket()
ws.connect("ws://truenas-host/websocket")

# Send API call
request = {
    "id": "unique-request-id",
    "method": "system.info",
    "params": []
}
ws.send(json.dumps(request))
```

## Troubleshooting

### Common Issues

**Connection Problems**:
- Verify TrueNAS host accessibility and WebSocket port (80/443)
- Check authentication credentials and API key validity
- Ensure TrueNAS version supports WebSocket API (25.04+)

**Authentication Errors**:
- Verify API key is properly configured in TrueNAS web interface
- Check user permissions for API access
- Ensure proper username/password for basic authentication

**API Call Failures**:
- Validate API method names against version-specific documentation
- Check parameter formatting and required fields
- Review error responses for specific failure reasons

### Development Resources

**API Client Documentation**: https://github.com/truenas/api_client/blob/main/README.md
**Middleware Source**: https://github.com/truenas/middleware/
**Community Support**: TrueNAS Community Forums and Discord

## LLM Usage Guidelines

### API Version Context
- **Default approach**: Use latest stable version for general queries (check https://api.truenas.com/ for current stable)
- **User-specified versions**: When users mention a specific TrueNAS version, use that version's API documentation
- **URL construction**: Build version-specific URLs using pattern `https://api.truenas.com/v{version}/`
- **Version compatibility**: API methods and events may vary between versions - always reference the appropriate version's documentation

### Response Strategy
- **Code examples**: Provide practical API usage examples when possible
- **Error handling**: Include proper error handling in code samples
- **Security considerations**: Always mention authentication and security best practices
- **Real-world context**: Connect API methods to actual TrueNAS management tasks

### Content Integration
- **Cross-reference with main docs**: Link to https://truenas.com/docs/ for broader context
- **UI correlation**: Reference corresponding web interface locations when helpful
- **Best practices**: Include performance and security recommendations

## Cross-References

### Main TrueNAS Documentation
- **System Administration**: https://truenas.com/docs/scale/25.04/gettingstarted/ - Initial setup and basic configuration
- **Storage Management**: https://truenas.com/docs/scale/25.04/storage/ - Pool and dataset management concepts
- **Network Configuration**: https://truenas.com/docs/scale/25.04/network/ - Network setup and troubleshooting
- **Data Sharing**: https://truenas.com/docs/scale/25.04/shares/ - File sharing service configuration

### TrueNAS Apps Documentation
- **App Deployment**: https://apps.truenas.com/managing-apps/installing-apps/ - Container application setup
- **App Management**: https://apps.truenas.com/managing-apps/managing-installed-apps/ - Application lifecycle management

### Development Resources
- **API Client Repository**: https://github.com/truenas/api_client - Official Python client library
- **Middleware Repository**: https://github.com/truenas/middleware/ - Core TrueNAS backend code
- **Community Resources**: https://truenas.com/community/ - Forums and community support

## Error Scenarios

### Version Compatibility Issues
If users encounter API method deprecation or version conflicts:
1. Check the specific TrueNAS version being used
2. Reference the appropriate version's API documentation
3. Note any method changes between versions
4. Suggest upgrade paths if using deprecated methods

### Authentication and Access Issues
For API access problems:
1. Verify TrueNAS version supports WebSocket API (available 24.10+, introduced in 25.04)
2. Guide through API key generation in web interface
3. Check user account permissions for API access
4. Troubleshoot network connectivity to WebSocket endpoint

### Integration and Development Issues
For developers building TrueNAS integrations:
1. Reference official API client library first
2. Provide WebSocket connection examples
3. Include proper error handling patterns
4. Point to middleware source code for advanced use cases