¶ API Endpoints
¶ Table of Contents
- Requirements
- Installation
- Configuration
- API Endpoints
- Ticket Management API
- Subticket Management API
- API Key Permissions
- Troubleshooting
- Technical Details
- FAQ
¶ Overview
Extends osTicket's REST API with powerful endpoints for advanced ticket management. Enables ticket creation with Markdown formatting, department routing, subticket support, and comprehensive ticket management (update, retrieve, search, delete, statistics).
Perfect for integrations that need granular control beyond osTicket's standard API capabilities - ideal for support portals, bug trackers, automation platforms (Zapier/Make.com), and custom workflows.
¶ Key Features
- ✅ Extended Ticket Creation - Markdown formatting, department routing, subticket support
- ✅ Ticket Management - Update, retrieve, search, delete tickets via API
- ✅ Due Date Management - Set/update/clear due dates with automatic overdue flag reset
- ✅ Subticket API - Manage parent-child relationships between tickets
- ✅ Ticket Statistics - Get comprehensive stats (global, by department, by staff)
- ✅ Granular Permissions - Fine-grained API key permissions (create, read, update, search, delete, subtickets)
- ✅ Name-Based Filters - Use human-readable names instead of IDs
- ✅ No Core Modifications - Signal-based architecture (update-safe)
- ✅ TDD-Tested - 168 tests with comprehensive coverage
- ✅ Apache & NGINX Support - Automatic .htaccess configuration for Apache, NGINX config examples
- ✅ JSON & XML Support - Flexible response formats for all GET endpoints
¶ Use Cases
- Support Portals - Create tickets directly in specific departments
- Bug Trackers - Submit tickets with Markdown-formatted code snippets
- Follow-Up Workflows - Automatically create subtickets for escalations
- Automation Platforms - Zapier/Make.com integrations with rich formatting
- Team Management - Search, update, and analyze tickets programmatically
- Dashboards - Display real-time ticket statistics and metrics
- CI/CD Pipelines - Automatic ticket creation on build failures or deployment issues
- Monitoring Systems - Integration with Nagios, Zabbix, Prometheus for alert tickets
- CRM Integration - Sync support tickets with Salesforce, HubSpot
- Self-Service Portals - Enable customers to create tickets through custom interfaces
¶ Requirements
| Requirement | Version | Notes |
|---|---|---|
| osTicket | 1.18.x | Plugin extends API via Signal system |
| PHP | 8.1+ | Uses modern PHP features: enums, union types, named arguments |
| Web Server | Apache 2.4+ or NGINX 1.18+ | Apache: .htaccess support required |
| Parsedown | Automatic | Included in Composer lock |
Optional Dependencies:
| Plugin | Purpose | Link |
|---|---|---|
| Markdown Support | Markdown rendering in tickets | GitHub |
| Subticket Manager | UI for subticket management | GitHub |
| API Key Wildcard | Wildcard IP validation for API keys | GitHub |
¶ Installation
¶ Step 1: Install Plugin Files
¶ Method 1: ZIP Download (Recommended)
- Download the latest release from Releases
- Extract the ZIP file
- Upload the
api-endpointsfolder to/include/plugins/on your osTicket server
Final path: /path/to/osticket/include/plugins/api-endpoints/
¶ Method 2: Git Repository
cd /path/to/osticket/include/plugins
git clone https://github.com/markus-michalski/osticket-api-endpoints.git
¶ Step 2: Enable Plugin in osTicket
- Login to osTicket Admin Panel
- Navigate to: Admin Panel → Manage → Plugins
- Find "API Endpoints" in the list
- Click "Enable"
The plugin automatically configures:
- Signal hooks for API routing
- Apache .htaccess for PATH_INFO support
- Composer dependencies (Parsedown)
¶ Step 3: Configure Web Server
¶ Apache (Automatic)
On activation, the plugin automatically deploys /api/.htaccess:
# osTicket API Endpoints Plugin - Apache Configuration
<IfModule mod_rewrite.c>
RewriteEngine On
# Enable PATH_INFO for all API endpoints
AcceptPathInfo On
# Rewrite rules for endpoints with path info
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(tickets-update|tickets-get|tickets-delete)\.php/(.+)$ $1.php [L,QSA]
</IfModule>
# Allow PATH_INFO for endpoints
<Files "tickets-update.php">
AcceptPathInfo On
</Files>
<Files "tickets-get.php">
AcceptPathInfo On
</Files>
<Files "tickets-delete.php">
AcceptPathInfo On
</Files>
Verify .htaccess is working:
curl -I "https://your-domain.com/api/tickets-get.php/123456.json" \
-H "X-API-Key: YOUR_API_KEY"
# Should return 200 OK (not 404)
¶ NGINX (Manual Configuration)
Add the following configuration to your NGINX server block:
# osTicket API Endpoints Plugin - NGINX Configuration
# Endpoints with PATH_INFO (e.g., /api/tickets-update.php/123456.json)
location ~ ^/api/tickets-(update|get|delete)\.php/ {
fastcgi_split_path_info ^(/api/tickets-(update|get|delete)\.php)(/.+)$;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php-fpm.sock; # Or 127.0.0.1:9000
}
# Endpoints without PATH_INFO (e.g., /api/tickets-search.php?query=test)
location ~ ^/api/tickets-(search|stats|statuses)\.php$ {
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php-fpm.sock;
}
# Subticket endpoints with PATH_INFO
location ~ ^/api/tickets-subtickets-(parent|list)\.php/ {
fastcgi_split_path_info ^(/api/tickets-subtickets-(parent|list)\.php)(/.+)$;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php-fpm.sock;
}
# Subticket endpoints without PATH_INFO
location ~ ^/api/tickets-subtickets-(create|unlink)\.php$ {
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
fastcgi_pass unix:/var/run/php/php-fpm.sock;
}
After adding configuration:
# Test configuration
sudo nginx -t
# Reload NGINX
sudo systemctl reload nginx
# Test endpoint
curl "https://your-domain.com/api/tickets-stats.php" \
-H "X-API-Key: YOUR_API_KEY"
¶ Step 4: Configure API Key Permissions
After plugin installation, you need to configure API Key permissions to grant access to the new endpoints.
Configure API Key Permissions:
- Navigate to: Admin Panel → Manage → API Keys
- Select your API key (or create a new one)
- Click "Manage Permissions"
- Enable the desired API Endpoint Permissions:
- ✅ Create Tickets (
POST /tickets) - ✅ Update Tickets (
PATCH /tickets/:id) - ✅ Read Tickets (
GET /tickets/:number) - ✅ Search Tickets (
GET /tickets/search) - ✅ Delete Tickets (
DELETE /tickets/:number) - Optional, disabled by default for security - ✅ Read Stats (
GET /tickets-stats) - ✅ Manage Subtickets (Subticket Operations)
- ✅ Create Tickets (
- Click "Save"
Screenshot Example:
The API Key configuration shows permissions like:
☑ Create Tickets (can_create_tickets)
☑ Read Tickets (can_read_tickets)
☑ Update Tickets (can_update_tickets)
☑ Search Tickets (can_search_tickets)
☐ Delete Tickets (can_delete_tickets) [Disabled for security]
☑ Read Statistics (can_read_stats)
☑ Manage Subtickets (can_manage_subtickets)
¶ Configuration
After plugin installation, a new configuration page appears under Admin Panel → Plugins → API Endpoints → Configure, displaying all available endpoints with their associated permissions:
Available API Endpoints:
- ✓ POST /tickets - Create tickets with format (markdown/html/text) and department
- Controlled by:
can_create_ticketspermission
- Controlled by:
- ✓ GET /tickets/:number - Retrieve ticket details
- Controlled by:
can_read_ticketspermission
- Controlled by:
- ✓ PATCH /tickets/:number - Update ticket (status, department, SLA, dueDate, etc.)
- Controlled by:
can_update_ticketspermission
- Controlled by:
- ✓ GET /tickets/search - Search tickets
- Controlled by:
can_search_ticketspermission
- Controlled by:
- ✗ DELETE /tickets/:number - Permanently delete ticket
- Controlled by:
can_delete_ticketspermission - ⚠️ Disabled by default for security - Only enable if absolutely necessary!
- Controlled by:
- ✓ GET /tickets-stats - Retrieve ticket statistics
- Controlled by:
can_read_statspermission
- Controlled by:
- ✓ GET /tickets-statuses - List available statuses
- Controlled by:
can_read_statspermission
- Controlled by:
- ✓ Subticket Endpoints - Manage parent-child relationships
- Controlled by:
can_manage_subticketspermission
- Controlled by:
Important: The plugin configuration page is informational only and shows which endpoints are available. Actual access to each endpoint is controlled individually per API Key via the API Key permissions system (see API Key Permissions).
¶ API Endpoints
¶ Overview
The plugin provides 11 REST endpoints:
| Endpoint | Method | Description |
|---|---|---|
/api/tickets.json |
POST | Extended ticket creation (Markdown, Department, Subticket) |
/api/tickets-get.php/{number}.json |
GET | Retrieve ticket details |
/api/tickets-update.php/{number}.json |
PATCH | Update ticket (Status, Department, SLA, dueDate, etc.) |
/api/tickets-search.php |
GET | Search tickets |
/api/tickets-delete.php/{number}.json |
DELETE | Permanently delete ticket |
/api/tickets-stats.php |
GET | Ticket statistics (global, Department, Staff) |
/api/tickets-statuses.php |
GET | List available ticket statuses |
/api/tickets-subtickets-parent.php/{id}.json |
GET | Get parent ticket of a subticket |
/api/tickets-subtickets-list.php/{id}.json |
GET | Get all child tickets of a parent |
/api/tickets-subtickets-create.php |
POST | Create parent-child relationship |
/api/tickets-subtickets-unlink.php |
DELETE | Remove parent-child relationship |
All GET endpoints support both JSON and XML:
.jsonfor JSON response.xmlfor XML response
¶ Ticket Management API
¶ 3. PATCH Update Ticket
Update ticket properties such as status, department, priority, SLA plan, staff assignment, and due date.
URL: PATCH /api/tickets-update.php/{number}.{format}
Updatable Fields:
| Field | Type | Description | Example |
|---|---|---|---|
statusId |
string/int | Status name or ID | "Resolved" or 3 |
departmentId |
string/int | Department name or ID | "Sales" or 7 |
topicId |
int | Help Topic ID | 15 |
slaId |
string/int | SLA Plan name or ID | "Premium Support" or 2 |
staffId |
string/int | Staff username or ID | "john.doe" or 5 |
teamId |
int | Team ID for assignment | 3 |
priority |
string/int | Priority name or ID | "Urgent", "High" or 4 |
dueDate |
string/null | Due date (ISO 8601) or null to clear |
"2026-01-31" or "2026-01-31T17:30:00" |
note |
string | Add internal note (staff only) | "Customer called for status update" |
¶ Due Date (dueDate) Parameter
The dueDate parameter allows you to set, update, or clear the ticket's due date.
Behavior:
- Set: Pass an ISO 8601 formatted date string
- Update: Pass a new date (overwrites existing)
- Clear: Pass
nullto remove the due date - Overdue Flag: When setting a future due date, the
isOverdueflag is automatically cleared
Examples:
Set due date:
curl -X PATCH "https://osticket.local/api/tickets-update.php/123456.json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dueDate": "2026-01-31"
}'
Set due date with time:
curl -X PATCH "https://osticket.local/api/tickets-update.php/123456.json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dueDate": "2026-01-31T17:30:00"
}'
Clear due date:
curl -X PATCH "https://osticket.local/api/tickets-update.php/123456.json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"dueDate": null
}'
Combined with other fields:
curl -X PATCH "https://osticket.local/api/tickets-update.php/123456.json" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"statusId": "Open",
"priority": "High",
"dueDate": "2026-02-15",
"note": "Due date updated, priority raised"
}'
Response:
{
"success": true,
"message": "Ticket updated successfully",
"ticket_id": 123456,
"number": "ABC123",
"updated_fields": ["dueDate", "priority"]
}
Error Response (invalid date):
{
"error": "Invalid date format for dueDate. Expected ISO 8601 format (e.g., \"2025-01-31\" or \"2025-01-31T17:30:00\")"
}
¶ Automatic Overdue Flag Reset
When you set a dueDate that is in the future (greater than current time), the plugin automatically calls clearOverdue() on the ticket. This:
- Resets the
isOverdueflag from1to0 - Updates the ticket's internal state
- Prevents the ticket from appearing in "Overdue" filters
This behavior only triggers when:
- The new
dueDateis different from the current due date - The new
dueDateis in the future - The ticket currently has
isOverdue = 1
¶ API Key Permissions
The plugin extends osTicket's API key permission system with granular permissions.
¶ Available Permissions
| Permission | Database Field | Grants Access To |
|---|---|---|
| Create Tickets | can_create_tickets |
POST /tickets |
| Read Tickets | can_read_tickets |
GET /tickets/:number |
| Update Tickets | can_update_tickets |
PATCH /tickets/:number |
| Search Tickets | can_search_tickets |
GET /tickets/search |
| Delete Tickets | can_delete_tickets |
DELETE /tickets/:number |
| Read Statistics | can_read_stats |
GET /tickets-stats, GET /tickets-statuses |
| Manage Subtickets | can_manage_subtickets |
All subticket endpoints |
¶ Configure Permissions
- Navigate to: Admin Panel → Manage → API Keys
- Select API key from list
- Click Configure (gear icon)
- Enable/Disable permissions
- Click Save
Screenshot:
The plugin config adds a new tab "API Endpoints Permissions" with the following options:
☑ Create Tickets (can_create_tickets)
☑ Read Tickets (can_read_tickets)
☑ Update Tickets (can_update_tickets)
☑ Search Tickets (can_search_tickets)
☐ Delete Tickets (can_delete_tickets) [Disabled for security]
☑ Read Statistics (can_read_stats)
☑ Manage Subtickets (can_manage_subtickets)
¶ Backward Compatibility
The plugin supports legacy API keys (without new permissions):
- If
can_create_ticketsmissing → fallback tocanCreateTickets()(osTicket standard) - If
can_read_ticketsmissing → fallback tocanCreateTickets()(READ = CREATE allowed) - If
can_update_ticketsmissing → fallback tocanCreateTickets()
Recommendation: Migrate to new permissions for fine-grained control.
¶ Best Practices
-
Principle of Least Privilege:
- Only enable required permissions
- Separate API keys for different integrations
- Monitoring dashboard → only
can_read_stats - CI/CD pipeline → only
can_create_tickets
-
Rotation & Revocation:
- Rotate API keys regularly (every 90 days)
- Disable unused keys
- Use API Key Wildcard Plugin for IP restrictions
-
Audit Logging:
- Enable osTicket's API audit log
- Admin Panel → Settings → API → Log API requests
- Monitor unusual activity
¶ Troubleshooting
¶ Problem: 404 Not Found for endpoints with PATH_INFO
Symptoms:
curl "https://osticket.local/api/tickets-get.php/123456.json"
# HTTP 404 Not Found
Cause: Apache/NGINX not configured for PATH_INFO.
Solution (Apache):
-
Check if
/api/.htaccessexists:ls -la /path/to/osticket/api/.htaccess -
If missing, re-enable plugin (deploys .htaccess automatically)
-
Check Apache configuration:
# In VirtualHost or .conf <Directory /path/to/osticket/api> AllowOverride All </Directory> -
Reload Apache:
sudo systemctl reload apache2
Solution (NGINX):
-
Add PATH_INFO configuration (see Installation → NGINX)
-
Test configuration:
sudo nginx -t -
Reload NGINX:
sudo systemctl reload nginx
¶ Problem: Markdown not rendering
Symptoms:
- Ticket message shows raw Markdown text (
**bold**instead of bold) - Format parameter ignored
Check:
-
Markdown Support Plugin installed?
ls /path/to/osticket/include/plugins/markdown-support -
Plugin enabled?
- Admin Panel → Plugins → Markdown Support → Status: Enabled
-
API request correct?
curl -X POST "https://osticket.local/api/tickets.json" \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Test", "email": "test@example.com", "subject": "Markdown Test", "message": "## Heading\n\n**Bold text**", "format": "markdown" # ← Important! }' -
Plugin configuration:
- Admin Panel → Plugins → API Endpoints → Configure
- Check if Markdown endpoints are available
Workaround: If Markdown Support Plugin unavailable:
- Use
format: "html"instead offormat: "markdown" - Convert Markdown to HTML before API request (e.g., with Pandoc)
¶ Problem: 403 Forbidden on API requests
Symptoms:
{
"error": "API key not authorized for this operation"
}
Cause: API key has missing permissions.
Solution:
-
Check API key permissions:
- Admin Panel → Manage → API Keys → [Your Key] → Configure
- Enable required permission:
- POST /tickets →
can_create_tickets - GET /tickets/:number →
can_read_tickets - PATCH /tickets/:number →
can_update_tickets - DELETE /tickets/:number →
can_delete_tickets - GET /tickets/search →
can_search_tickets - GET /tickets-stats →
can_read_stats - Subticket endpoints →
can_manage_subtickets
- POST /tickets →
-
Re-enable plugin after update:
- After plugin updates: Admin Panel → Plugins → API Endpoints → Disable → Enable
- This creates new database columns for permissions
-
Check fallback permission:
- If new permissions missing, plugin uses
canCreateTickets()as fallback - Enable: Admin Panel → Manage → API Keys → [Your Key] → Can Create Tickets
- If new permissions missing, plugin uses
¶ License
This Plugin is released under the GNU General Public License v2, compatible with osTicket core.
See LICENSE for details.
¶ Support
For questions or issues, please create an issue on GitHub:
Issue Tracker: https://github.com/markus-michalski/osticket-api-endpoints/issues
When reporting issues, please include:
- osTicket version (Admin Panel → Settings → About)
- PHP version (
php -v) - Plugin version
- Web server (Apache/NGINX + version)
- Request example (cURL command)
- Response/Error message
¶ Contributing
Developed by Markus Michalski
Contributions welcome!
- Fork the repository
- Create a feature branch
- Submit a pull request
Development Setup:
# Clone repository
git clone https://github.com/markus-michalski/osticket-api-endpoints.git
cd osticket-api-endpoints
# Install dependencies
composer install
# Run tests
composer test
# Check code style
composer cs-check
¶ Changelog
See CHANGELOG.md for version history.