Heyo,
I have potential update for the API page if someone can give it a look over and deets on how to contribute to the docs.
# ITFlow Complete API Reference & Knowledge Base
**Current API v1 Endpoints, Authentication, Examples, and Integration Guide**
## 🚀 **Quick Start Guide**
### **Your First API Call in 5 Minutes**
1. **Generate API Key**
- Login to ITFlow as admin
- Navigate to **Admin > API**
- Click **"New Key"**
- Choose scope: **All Clients** (for testing) or **Specific Client**
- Copy the generated key
2. **Test Connection**
```bash
curl "https://your-itflow.com/api/v1/clients/read.php?api_key=YOUR_KEY&limit=1"
```
3. **Expected Response**
```json
{
"success": "True",
"count": 1,
"data": [{"client_id": "123", "client_name": "Example Corp"}]
}
```
## 📋 **API Overview**
**Source**: ITFlow codebase analysis and API endpoint testing
- **Base URL**: `/api/v1/`
- **Version**: 1.0 (current)
- **Authentication**: API Key via query parameter `?api_key=YOUR_KEY`
- **Response Format**: JSON with `success`, `message`, `count`, `data` fields
- **Pagination**: Default 50 records, adjustable with `limit` and `offset` parameters
- **Content-Type**: `application/json` for POST requests
- **Character Encoding**: UTF-8 (utf8mb4 in database)
### **Standard Response Format**
**Source**: Observed API responses across all endpoints
```json
{
"success": "True|False",
"message": "Descriptive status message",
"count": 50,
"data": [
{
"id": 123,
"field": "value"
}
]
}
```
---
## 🔐 **Authentication & Security**
### **API Key Management**
- **Generation**: Admin > API > New Key
- **Scoping Options**:
- **All Clients**: Full access to all client data
- **Specific Client**: Limited to single client (client_id required)
- **Usage**: Query parameter `?api_key=YOUR_KEY`
- **Security**: Keys stored encrypted in database
### **Best Practices**
**Source**: MSP community recommendations and security standards
- **Rotate keys** regularly (monthly recommended)
- **Use client-scoped keys** for third-party integrations
- **Store keys securely** (environment variables, not code)
- **Monitor usage** via Apache/PHP logs
- **Use HTTPS only** for all API calls
### **Rate Limiting**
**Source**: No official documentation found - based on system observation
- **Current Status**: No official rate limiting implemented
- **Recommendation**: Implement delays between bulk operations
- **Courtesy Limit**: 100 requests/minute suggested (community best practice)
---
## 🔧 **Currently Available Modules**
### **Assets** `/api/v1/assets/`
**Purpose**: Computer and equipment inventory management
**Source**: [ITFlow Assets Documentation](https://docs.itflow.org/assets)
- `GET /read.php` - List/get asset information
- `POST /create.php` - Create new asset record
- `POST /update.php` - Update existing asset
- `POST /delete.php` - Delete asset record
**Complete Fields** (from [ITFlow Assets API Documentation](https://docs.itflow.org/assets)):
```json
{
"asset_id": 123,
"client_id": 456,
"asset_name": "Sample Laptop",
"asset_type": "Laptop|Desktop|Server|Virtual Machine|Printer|Network Device|Mobile Device|Tablet|Other",
"asset_make": "Dell",
"asset_model": "Optiplex",
"asset_serial": "XYZ",
"asset_os": "Win 10",
"asset_ip": "192.168.1.100",
"asset_mac": "00:11:22:33:44:55",
"asset_status": "Deployed|Active|Inactive|In Repair|Retired|Lost/Stolen",
"asset_purchase_date": "2024-01-15",
"asset_warranty_expire": "2027-01-15",
"install_date": "2024-01-15",
"asset_notes": "Additional notes",
"asset_vendor_id": 789,
"asset_location_id": 101,
"asset_contact_id": 202,
"asset_network_id": 303,
"asset_created_at": "2024-01-15 10:30:00",
"asset_updated_at": "2024-01-15 11:00:00",
"asset_archived_at": null
}
```
**API Example Source**: PowerShell create example from ITFlow docs showing complete field usage
### **Certificates** `/api/v1/certificates/`
**Purpose**: SSL/TLS certificate management and expiration tracking
**Source**: [ITFlow Certificates Documentation](https://docs.itflow.org/certificates)
- `GET /read.php` - List/get certificate information
- `POST /create.php` - Create certificate record
- `POST /update.php` - Update certificate details
- `POST /delete.php` - Delete certificate record
**Complete Fields** (from [ITFlow Certificates API Documentation](https://docs.itflow.org/certificates)):
```json
{
"certificate_id": 123,
"client_id": 456,
"certificate_name": "ITFlow Demo",
"certificate_domain": "demo.itflow.org",
"certificate_issued_date": "2024-01-01",
"certificate_expire_date": "2025-01-01",
"certificate_issuer": "Let's Encrypt",
"certificate_public_key": "[Certificate content]",
"certificate_notes": "Auto-renewal enabled",
"certificate_created_at": "2024-01-01 10:00:00",
"certificate_updated_at": "2024-01-01 10:30:00",
"certificate_archived_at": null
}
```
**API Example Source**: PowerShell read example from ITFlow docs showing API response structure
### **Clients** `/api/v1/clients/`
**Purpose**: Customer/company management
**Source**: [ITFlow Clients Documentation](https://docs.itflow.org/clients)
- `GET /read.php` - List/get client information
- `POST /create.php` - Create new client
- `POST /update.php` - Update client details
- `POST /delete.php` - Delete client record
**Complete Fields** (from [ITFlow Clients API Documentation](https://docs.itflow.org/clients)):
```json
{
"client_id": 123,
"client_lead": 0,
"client_name": "Let it burn Inc",
"client_type": "Safety and Fire",
"client_website": "example.com",
"client_phone": "555-0123",
"client_email": "contact@acme.com",
"client_address": "123 Business St",
"client_city": "Toronto",
"client_state": "ON",
"client_zip": "M1M 1M1",
"client_country": "Canada",
"client_notes": "Premium support client",
"client_currency_code": "CAD",
"client_net_terms": 30,
"client_tax_id_number": "123456789",
"client_abbreviation": "LITB",
"client_referral_partner": 0,
"client_rate": 150.00,
"client_created_at": "2024-01-01 09:00:00",
"client_updated_at": "2024-01-01 10:00:00",
"client_archived_at": null,
"client_access_token": "[Portal access token]"
}
```
**API Example Source**: PowerShell read example from ITFlow docs showing actual API response with "Let it burn Inc" example data
### **Contacts** `/api/v1/contacts/`
**Purpose**: Individual contact management within client organizations
**Source**: [ITFlow Contacts Documentation](https://docs.itflow.org/clients) (Contact management documented within client docs)
- `GET /read.php` - List/get contact information
- `POST /create.php` - Create new contact
- `POST /update.php` - Update contact details
- `POST /delete.php` - Delete contact record
**Complete Fields** (from [GitHub Issue #458](https://github.com/itflow-org/itflow/issues/458) and database update scripts):
```json
{
"contact_id": 123,
"client_id": 456,
"contact_name": "John Smith",
"contact_title": "IT Manager",
"contact_email": "john.smith@acme.com",
"contact_phone": "555-0124",
"contact_extension": "101",
"contact_mobile": "555-0125",
"contact_fax": "555-0126",
"contact_department": "Information Technology",
"contact_location_id": 1,
"contact_notes": "Primary technical contact",
"contact_primary": 1,
"contact_important": 0,
"contact_billing": 1,
"contact_technical": 1,
"contact_password_hash": "[Encrypted]",
"contact_password_changed_at": "2024-01-01",
"contact_pin": "1234",
"contact_auth_method": "local",
"contact_photo": "/uploads/contact_photo.jpg",
"contact_created_at": "2024-01-01 09:00:00",
"contact_updated_at": "2024-01-01 10:00:00",
"contact_archived_at": null,
"contact_vendor_id": 0,
"contact_user_id": 0
}
```
**Field Sources**: Database migration scripts in GitHub repository showing complete contact table structure
### **Credentials** `/api/v1/credentials/`
**Purpose**: Password and login management (encrypted storage)
**Source**: [ITFlow Passwords Documentation](https://docs.itflow.org/passwords)
- `GET /read.php` - List/get credential information
- `POST /create.php` - Create new credential record
- `POST /update.php` - Update credential details
- `POST /delete.php` - Delete credential record
**Complete Fields** (from [ITFlow Passwords Documentation](https://docs.itflow.org/passwords) and [GitHub database migration scripts](https://github.com/itflow-org/itflow/blob/master/database_updates.php)):
```json
{
"credential_id": 123,
"client_id": 456,
"credential_name": "Domain Admin",
"credential_description": "Active Directory administrator",
"credential_username": "admin",
"credential_password": "[ENCRYPTED]",
"credential_password_changed_at": "2024-01-01",
"credential_uri": "https://login.example.com",
"credential_uri_2": "https://backup-login.example.com",
"credential_notes": "Changed quarterly",
"credential_one_time": 0,
"credential_important": 1,
"credential_contact_id": 789,
"credential_vendor_id": 101,
"credential_asset_id": 202,
"credential_software_id": 303,
"credential_domain_id": 404,
"credential_created_at": "2024-01-01 09:00:00",
"credential_updated_at": "2024-01-01 10:00:00",
"credential_archived_at": null,
"login_folder_id": 0
}
```
**Field Sources**: ITFlow passwords documentation explains encryption model; database updates show login_folder_id addition
### **Domains** `/api/v1/domains/`
**Purpose**: Domain name management and renewal tracking
**Source**: [ITFlow Domains Documentation](https://docs.itflow.org/domains)
- `GET /read.php` - List/get domain information
- `POST /create.php` - Create domain record
- `POST /update.php` - Update domain details
- `POST /delete.php` - Delete domain record
**Complete Fields** (from [ITFlow Domains API Documentation](https://docs.itflow.org/domains)):
```json
{
"domain_id": 123,
"client_id": 456,
"domain_name": "itflow.org",
"domain_registrar": "GoDaddy",
"domain_registrar_account_id": "12345",
"domain_webhost": "SiteGround",
"domain_expire": "2025-03-15",
"domain_ip": "192.168.1.1",
"domain_name_servers": "ns1.example.com, ns2.example.com",
"domain_mail_servers": "mx1.example.com",
"domain_txt_records": "v=spf1 include:_spf.google.com ~all",
"domain_raw_whois": "[Raw WHOIS data]",
"domain_notes": "Auto-renewal enabled",
"domain_created_at": "2022-02-05 18:15:07",
"domain_updated_at": "2024-01-01 10:00:00",
"domain_archived_at": null
}
```
**API Example Source**: PowerShell read example from ITFlow docs showing "itflow.org" domain with actual timestamps
### **Networks** `/api/v1/networks/`
**Purpose**: Network infrastructure documentation
**Source**: [ITFlow GitHub Database Updates](https://github.com/itflow-org/itflow/blob/master/database_updates.php) (Interface migration scripts)
- `GET /read.php` - List/get network information
- `POST /create.php` - Create network record
- `POST /update.php` - Update network details
- `POST /delete.php` - Delete network record
**Complete Fields** (from [GitHub database migration scripts](https://github.com/itflow-org/itflow/blob/master/database_updates.php) showing network interface relationships):
```json
{
"network_id": 123,
"client_id": 456,
"network_name": "Main Office LAN",
"network": "192.168.1.0/24",
"network_gateway": "192.168.1.1",
"network_dhcp_range": "192.168.1.100-192.168.1.200",
"network_dhcp_options": "Option 66: 192.168.1.10",
"network_vlan": "10",
"network_location_id": 789,
"network_notes": "Primary office network",
"network_created_at": "2024-01-01 09:00:00",
"network_updated_at": "2024-01-01 10:00:00",
"network_archived_at": null
}
```
**Field Sources**: Database migration scripts show network-to-interface relationship migration and interface table creation
### **Software** `/api/v1/software/`
**Purpose**: Software license and application tracking
**Source**: [ITFlow API Documentation](https://docs.itflow.org/api) (Listed as available module)
- `GET /read.php` - List/get software information
- `POST /create.php` - Create software record
- `POST /update.php` - Update software details
- `POST /delete.php` - Delete software record
**Status**: ⚠️ **API ENDPOINTS LISTED BUT DOCUMENTATION MISSING**
**Available Fields**: *Unable to determine from available documentation*
```json
{
"software_id": "Unknown - no complete field specification found",
"client_id": "Required for all modules",
"Note": "This module is listed in ITFlow API documentation as available, but specific field specifications are not documented"
}
```
**Research Sources**:
- ITFlow codebase shows "software" module in API structure
- [ITFlow main site](https://itflow.org/) mentions "software licenses" in feature descriptions
- No dedicated module documentation found
- No API examples found in [PowerShell repository](https://github.com/itflow-org/itflow-api-powershell)
- Database structure not evident in available migration scripts
### **Tickets** `/api/v1/tickets/`
**Purpose**: Help desk and issue tracking
**Source**: [ITFlow Tickets Documentation](https://docs.itflow.org/tickets)
- `GET /read.php` - List/get ticket information
- `POST /create.php` - Create new ticket
- `POST /update.php` - Update ticket details
- `POST /delete.php` - Delete ticket record
**Complete Fields** (from [ITFlow Tickets API Documentation](https://docs.itflow.org/tickets) and [GitHub Issue #298](https://github.com/itflow-org/itflow/issues/298)):
```json
{
"ticket_id": 123,
"client_id": 456,
"contact_id": 789,
"ticket_prefix": "TCK-",
"ticket_number": 3,
"ticket_category": "Hardware",
"ticket_subject": "Computer broken",
"ticket_details": "User cannot send emails from Outlook",
"ticket_priority": "High|Medium|Low|Critical",
"ticket_status": "Open|Working|Waiting on Client|Waiting on Vendor|Resolved|Closed",
"ticket_vendor_ticket_number": "VENDOR-123",
"ticket_created_at": "2024-06-02 09:00:00",
"ticket_updated_at": "2024-06-02 10:30:00",
"ticket_closed_at": null,
"ticket_closed_by": 0,
"ticket_created_by": 5,
"ticket_assigned_to": 10,
"ticket_watchers": "user1@company.com,user2@company.com",
"ticket_asset_id": 202,
"ticket_vendor_id": 303,
"ticket_project_id": 0,
"ticket_billable": 1,
"ticket_onsite": 0,
"ticket_invoice_id": 0,
"ticket_estimate": 2.0,
"ticket_feedback": "Excellent service",
"ticket_archived_at": null
}
```
**Field Sources**: API example shows "Computer broken" ticket; GitHub issue #298 discusses ticket statistics SQL queries showing additional fields
---
## 📊 **Current API Capabilities**
### **Standard Operations** (All Modules)
- **READ**: Retrieve single record or list of records
- **CREATE**: Add new records with validation
- **UPDATE**: Modify existing records (partial support)
- **DELETE**: Remove records (partial support)
### **Query Parameters** (read.php endpoints)
- `client_id` - Filter by specific client
- `limit` - Number of records to return (default: 50)
- `offset` - Number of records to skip for pagination
- API key required on all requests
### **Response Format** (Standardized)
```json
{
"success": "True|False",
"message": "Descriptive message",
"count": 1,
"data": [
{
// Record data
}
]
}
```
---
## 🔒 **Current Authentication**
### **API Key Generation**
1. Navigate to Admin panel in ITFlow
2. Click on API section
3. Click "New Key" to generate
4. Choose scope: specific client or all clients
5. Copy generated key for use
### **API Key Usage**
- **Method**: Query parameter
- **Format**: `?api_key=YOUR_API_KEY`
- **Scope**: Can be limited to specific client or all clients
- **Access**: Currently all-or-nothing permissions
### **Security Features**
- **Encrypted Storage**: API keys stored securely
- **Client Scoping**: Keys can be limited to specific clients
- **Access Logging**: API usage tracked in logs
---
## ⚠️ **Current Limitations**
### **Missing CRUD Operations**
- **UPDATE**: Limited support across modules
- **DELETE**: Limited support across modules
- **ARCHIVE**: Not implemented
### **Missing Advanced Features**
- **Bulk Operations**: No batch create/update/delete
- **Advanced Search**: No full-text search or complex filtering
- **Webhooks**: No real-time event notifications
- **File Upload**: No direct file management API
- **Relationships**: Limited cross-module data retrieval
### **Missing Business Modules**
- **Invoices/Billing**: No financial transaction APIs
- **Quotes**: No sales proposal management
- **Time Tracking**: No billable hour recording
- **Calendar**: No scheduling or appointment APIs
- **Reports**: No automated report generation
### **Authentication Limitations**
- **Granular Permissions**: No module-specific access control
- **Rate Limiting**: No API abuse protection
- **OAuth**: Only API key authentication available
---
## 📈 **API Usage Examples**
### **Get All Clients**
```
GET /api/v1/clients/read.php?api_key=YOUR_KEY
```
### **Get Specific Asset**
```
GET /api/v1/assets/read.php?api_key=YOUR_KEY&asset_id=123
```
### **Create New Ticket**
```
POST /api/v1/tickets/create.php
Content-Type: application/json
{
"api_key": "YOUR_KEY",
"client_id": 456,
"ticket_subject": "Printer offline",
"ticket_details": "Office printer not responding",
"ticket_priority": "Medium"
}
```
### **List Client Assets**
```
GET /api/v1/assets/read.php?api_key=YOUR_KEY&client_id=456
```
---
## 🔄 **Integration Capabilities**
### **What Works Today**
- **Basic CRUD**: Create/read operations for core modules
- **Client Management**: Full customer database management
- **Asset Tracking**: Computer and equipment inventory
- **Ticket Creation**: Help desk ticket automation
- **Documentation**: Network, domain, certificate tracking
### **What's Missing for Full Automation**
- **Financial Operations**: No billing/invoicing automation
- **Real-time Events**: No webhook triggers for automation
- **Bulk Data Sync**: No efficient mass data operations
- **File Management**: No document upload/download APIs
- **Advanced Workflows**: No time tracking or scheduling APIs
---
## ⚠️ **Error Handling & Troubleshooting**
### **Standard Error Codes**
**Source**: HTTP standard codes - ITFlow API observed behavior
- **200**: Success - Request completed successfully
- **400**: Bad Request - Invalid parameters or malformed request
- **401**: Unauthorized - Invalid or missing API key
- **403**: Forbidden - API key lacks required permissions
- **404**: Not Found - Endpoint or record doesn't exist
- **500**: Server Error - Internal ITFlow error
### **Common Error Messages**
**Source**: Observed API responses and community reports
```json
{
"success": "False",
"message": "Invalid API key",
"count": 0,
"data": []
}
```
### **Troubleshooting Steps**
**Source**: Community experience and [ITFlow Installation Documentation](https://docs.itflow.org/installation)
1. **API Key Issues**
- Verify key is correct (copy/paste errors common)
- Check key scope (client-specific vs all clients)
- Confirm key hasn't been deactivated
2. **Permission Errors**
- Add `client_id` parameter for scoped keys
- Verify client_id exists and is accessible
3. **Server Errors**
- Check Apache/PHP error logs: `/var/log/apache2/error.log`
- Verify ITFlow database connectivity
- Check PHP memory limits for large requests
4. **Data Issues**
- Validate required fields for POST requests
- Check data types (strings, integers, dates)
- Verify foreign key relationships exist
### **Debug Mode**
**Source**: ITFlow admin settings and [ITFlow FAQ](https://docs.itflow.org/faq)
Enable PHP error reporting in ITFlow settings for detailed error messages during development.
---
## 🔧 **Integration Examples**
### **PowerShell Examples**
**Source**: [ITFlow PowerShell Repository](https://github.com/itflow-org/itflow-api-powershell)
**List All Clients**:
```powershell
$apiKey = "YOUR-API-KEY"
$baseUrl = "https://your-itflow.com"
$uri = "$baseUrl/api/v1/clients/read.php?api_key=$apiKey"
Thanks!