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_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_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_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!