ServiceOS Admin API Reference

The Valethon ServiceOS API provides programmatic access to the full admin interface — tickets, customers, assets, networks, billing, and more. It supports both session-based authentication for the admin SPA and API key authentication for external integrations.

Base URL: https://{tenant}.valethon.com/admin/api/v1

Authentication

The ServiceOS API supports two authentication methods:

Session-Based Authentication

Standard browser session via cookies. Used by the admin SPA and PHP-rendered pages. Sessions are tenant-specific (cookie name: VALETHON_{TENANT_SLUG}).

API Key Authentication

For programmatic access. API keys are scoped to specific modules with read/write/delete permissions.

Authorization: Bearer vsa_a1b2c3d4e5f6...

Key prefix: vsa_ (Valethon ServiceOS API)

API keys are managed via Settings → API Keys and support:

• Module-scoped permissions — e.g., tickets:read, tickets:write, assets:read
• Rate limiting — configurable per key
• Expiration — optional expiry date
• Audit logging — all API key requests are logged

Authentication Priority

• Check for active session (cookie-based)
• If no session, check Authorization: Bearer vsa_* header
• Validate key hash and module permissions
• Return auth context with auth_method (session or api_key)

Rate Limiting

API key requests are rate-limited per key. Session-based requests follow standard session rate limits.

Default limits:

Headers:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1710350460

Response Format

All API responses follow a consistent JSON structure:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": "Description of the error"
}

Paginated:

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 500,
    "total_pages": 20
  }
}

HTTP Status Codes

Tickets

Permission: tickets:read, tickets:write

GET /tickets.php

List tickets with filtering, sorting, and pagination.

Query Parameters:

Response (200):

{
  "success": true,
  "data": [
    {
      "ticket_id": 1042,
      "ticket_number": 3018,
      "subject": "Printer not working in main office",
      "description": "The HP LaserJet on floor 2 shows offline...",
      "status": "open",
      "priority": 3,
      "job_type": "Hardware",
      "company_number": 5,
      "company_name": "Acme Corp",
      "site_number": 12,
      "site_name": "Main Office",
      "assigned_to": 8,
      "assigned_name": "Mike Tech",
      "created_at": "2026-03-10T14:30:00Z",
      "updated_at": "2026-03-11T09:15:00Z",
      "closed_at": null
    }
  ],
  "pagination": { "page": 1, "per_page": 25, "total": 450, "total_pages": 18 }
}

POST /tickets.php

Create a new ticket.

Request:

{
  "subject": "VPN connection failing",
  "description": "Unable to connect to VPN since this morning. Error: timeout.",
  "priority": 3,
  "job_type": "Network",
  "company_number": 5,
  "site_number": 12,
  "assigned_to": 8
}

Response (201):

{
  "success": true,
  "data": {
    "ticket_id": 1043,
    "ticket_number": 3019,
    "status": "open"
  }
}

GET /tickets.php?id={id}

Get full ticket details including comments, assets, time entries, and contracts.

PUT /tickets.php?id={id}

Update ticket fields (status, priority, assignment, subject, description).

DELETE /tickets.php?id={id}

Delete a ticket.

GET /tickets.php?action=comments&id={id}

Get comments for a ticket.

POST /tickets.php?action=comments&id={id}

Add a comment to a ticket.

Request:

{
  "comment": "Checked the VPN server logs. Found certificate expiration issue.",
  "is_internal": true
}

GET /tickets.php?action=time-entries&id={id}

Get time entries for a ticket.

POST /tickets.php?action=time-entries&id={id}

Add a time entry.

Request:

{
  "duration_minutes": 45,
  "description": "Diagnosed VPN certificate issue and renewed certificates",
  "billable": true
}

GET /tickets.php?action=export

Export tickets to CSV or PDF.

Query Parameters:

Companies

GET /companies.php

List customer companies.

Query Parameters:

Response (200):

{
  "success": true,
  "data": [
    {
      "company_number": 5,
      "customer": "Acme Corp",
      "address": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "zip": "62701",
      "phone": "555-0100",
      "status": "Active",
      "site_count": 3,
      "open_tickets": 12
    }
  ],
  "pagination": { ... }
}

GET /companies.php?id={id}

Get company details with modules, sites, and summary statistics.

POST /companies.php

Create a new company.

PUT /companies.php?id={id}

Update company information.

DELETE /companies.php?id={id}

Delete a company.

GET /companies.php?action=modules&id={id}

Get enabled modules for a company.

PUT /companies.php?action=modules&id={id}

Enable or disable modules for a company.

Sites

GET /sites.php

List sites for a company.

Query Parameters:

GET /sites.php?id={id}

Get site details with buildings, floors, rooms, and zone hierarchy.

POST /sites.php

Create a new site.

PUT /sites.php?id={id}

Update site information.

DELETE /sites.php?id={id}

Delete a site.

GET /sites.php?action=hierarchy&id={id}

Get the full site hierarchy (buildings, floors, rooms, zones).

Assets

GET /assets.php

List assets with filtering.

Query Parameters:

Response (200):

{
  "success": true,
  "data": [
    {
      "asset_id": 200,
      "asset_number": 45,
      "machine_name": "HP LaserJet Pro",
      "asset_type": "Printer",
      "serial_number": "SN12345",
      "company_number": 5,
      "company_name": "Acme Corp",
      "site_number": 12,
      "site_name": "Main Office",
      "status": "Active",
      "ip_address": "192.168.1.50",
      "mac_address": "AA:BB:CC:DD:EE:FF"
    }
  ],
  "pagination": { ... }
}

GET /assets.php?id={id}

Get asset details with ports, credentials, licenses, contracts, and software inventory.

POST /assets.php

Create a new asset.

PUT /assets.php?id={id}

Update asset information.

DELETE /assets.php?id={id}

Delete an asset.

GET /assets.php?action=ports&id={id}

Get network ports for an asset.

POST /assets.php?action=ports&id={id}

Add a network port.

PUT /assets.php?action=ports&id={id}&port_id={port_id}

Update port information.

DELETE /assets.php?action=ports&id={id}&port_id={port_id}

Delete a port.

GET /assets.php?action=software&id={id}

Get installed software for an asset.

GET /assets.php?action=topology&id={id}

Get network topology connections for an asset.

POST /assets.php?action=import

Bulk import assets from CSV.

Contacts (Employees)

GET /contacts.php

List contacts/employees for a company.

Query Parameters:

GET /contacts.php?id={id}

Get contact details.

POST /contacts.php

Create a new contact.

PUT /contacts.php?id={id}

Update contact information.

DELETE /contacts.php?id={id}

Delete a contact.

POST /contacts.php?action=import

Bulk import contacts from CSV.

Contracts

GET /contracts.php

List service contracts.

Query Parameters:

GET /contracts.php?id={id}

Get contract details with linked assets and renewal information.

POST /contracts.php

Create a new contract.

PUT /contracts.php?id={id}

Update contract information.

DELETE /contracts.php?id={id}

Delete a contract.

Licenses

GET /licenses.php

List software licenses.

Query Parameters:

GET /licenses.php?id={id}

Get license details with assigned assets.

POST /licenses.php

Create a new license.

PUT /licenses.php?id={id}

Update license information.

DELETE /licenses.php?id={id}

Delete a license.

Networks

GET /networks.php

List networks for a company.

Query Parameters:

Response (200):

{
  "success": true,
  "data": [
    {
      "network_id": 10,
      "description": "Main Office LAN",
      "network_address": "192.168.1.0",
      "subnet_mask": "255.255.255.0",
      "gateway": "192.168.1.1",
      "company_number": 5,
      "site_number": 12
    }
  ],
  "pagination": { ... }
}

GET /networks.php?id={id}

Get network details with IP address assignments.

POST /networks.php

Create a new network.

PUT /networks.php?id={id}

Update network information.

DELETE /networks.php?id={id}

Delete a network.

VLANs

GET /vlans.php

List VLANs.

Query Parameters:

GET /vlans.php?id={id}

Get VLAN details with assigned ports.

POST /vlans.php

Create a new VLAN.

PUT /vlans.php?id={id}

Update VLAN information.

DELETE /vlans.php?id={id}

Delete a VLAN.

Vendors

GET /vendors.php

List vendor companies.

Query Parameters:

GET /vendors.php?id={id}

Get vendor details with linked contracts and assets.

POST /vendors.php

Create a new vendor.

PUT /vendors.php?id={id}

Update vendor information.

DELETE /vendors.php?id={id}

Delete a vendor.

Billing

GET /billing/invoices.php

List invoices.

Query Parameters:

GET /billing/invoices.php?id={id}

Get invoice details with line items and payment history.

POST /billing/invoices.php

Create a new invoice.

PUT /billing/invoices.php?id={id}

Update invoice information.

GET /billing/payments.php

List payments.

POST /billing/payments.php

Record a payment.

GET /billing/subscriptions.php

List active subscriptions.

GET /billing/marketplace.php

List Service Stack (marketplace) products and subscriptions.

POST /billing/marketplace.php

Purchase a Service Stack product.

Connect (Collectors)

GET /connect/collectors.php

List registered collectors.

Response (200):

{
  "success": true,
  "data": [
    {
      "collector_id": "c-abc123",
      "company_number": 5,
      "site_number": 12,
      "site_name": "Main Office",
      "status": "active",
      "version": "0.2.0",
      "last_seen_at": "2026-03-13T14:00:00Z",
      "sync_status": "completed",
      "last_sync_at": "2026-03-13T13:55:00Z"
    }
  ]
}

POST /connect/collectors.php

Register a new collector.

PUT /connect/collectors.php?id={id}

Update collector configuration.

DELETE /connect/collectors.php?id={id}

Revoke a collector.

POST /connect/sync/discovery.php

Receive discovery data sync from a collector. See the Connect App documentation for sync payload format.

GET /connect/collector/commands

Poll for pending commands (used by collector).

POST /connect/collector/commands/{id}/complete

Report command execution result.

Discovery

GET /discovery/queue.php

Get the discovery processing queue.

POST /discovery/scan.php

Initiate a network discovery scan.

Request:

{
  "company_number": 5,
  "site_number": 12,
  "scan_type": "full",
  "subnet": "192.168.1.0/24"
}

GET /discovery/results.php

Get discovery scan results.

CRM

The CRM module has its own dedicated API with separate authentication. See CRM API Reference for complete documentation.

GET /crm/leads.php

List CRM leads (also available via CRM API).

GET /crm/pipeline.php

Get sales pipeline summary and stage counts.

GET /crm/dashboard.php

Get CRM dashboard metrics.

Knowledge Base

GET /kb/articles.php

List knowledge base articles.

Query Parameters:

GET /kb/articles.php?id={id}

Get article details with linked entities.

POST /kb/articles.php

Create a new article.

PUT /kb/articles.php?id={id}

Update an article.

DELETE /kb/articles.php?id={id}

Delete an article.

GET /kb/categories.php

List KB categories.

POST /kb/categories.php

Create a category.

Reports

GET /reports/metrics.php

Get dashboard KPIs and metrics.

Response (200):

{
  "success": true,
  "data": {
    "open_tickets": 45,
    "high_priority": 8,
    "avg_resolution_hours": 4.2,
    "tickets_today": 12,
    "tickets_this_week": 67,
    "sla_compliance": 94.5
  }
}

GET /reports.php

List available reports.

GET /reports.php?id={id}

Get report configuration.

POST /reports.php

Create a new report.

PUT /reports.php?id={id}

Update report configuration.

DELETE /reports.php?id={id}

Delete a report.

POST /reports.php?action=run&id={id}

Execute a report and return results.

GET /reports.php?action=export&id={id}

Export report to file (CSV, PDF, XLSX).

GET /reports/fields.php?source={source}

Get available fields for building reports.

Settings

GET /settings/api-keys.php

List API keys (masked, showing prefix only).

POST /settings/api-keys.php

Create a new API key.

Request:

{
  "name": "Monitoring Integration",
  "permissions": ["tickets:read", "tickets:write", "assets:read"],
  "expires_at": "2027-03-13T00:00:00Z"
}

Response (201):

{
  "success": true,
  "data": {
    "key_id": 5,
    "api_key": "vsa_a1b2c3d4e5f6g7h8i9j0...",
    "name": "Monitoring Integration",
    "prefix": "vsa_a1b2",
    "permissions": ["tickets:read", "tickets:write", "assets:read"],
    "expires_at": "2027-03-13T00:00:00Z"
  },
  "message": "Store this key securely. It will not be shown again."
}

PUT /settings/api-keys.php?id={id}

Update key name or permissions.

DELETE /settings/api-keys.php?id={id}

Revoke an API key.

GET /settings/dropdowns.php

List dropdown configurations.

PUT /settings/dropdowns.php

Update dropdown values.

GET /settings/email-templates.php

List email templates.

PUT /settings/email-templates.php?id={id}

Update an email template.

GET /settings/colors.php

Get branding and theme colors.

PUT /settings/colors.php

Update branding and theme colors.

Service Outages

GET /outages.php

List service outages and current status.

Query Parameters:

GET /outages.php?id={id}

Get outage details with status history.

POST /outages.php

Create a new outage record.

PUT /outages.php?id={id}

Update outage status (triggers notifications).

Request:

{
  "status": "operating_normally",
  "notes": "Issue has been resolved. Root cause was DNS misconfiguration.",
  "send_notification": true
}

GET /outage-services.php

List global service definitions.

GET /company-services.php?company_number={id}

Get services assigned to a company.

Workflows

GET /workflows.php

List workflow definitions.

GET /workflows.php?id={id}

Get workflow details with steps and conditions.

POST /workflows.php

Create a new workflow.

PUT /workflows.php?id={id}

Update a workflow definition.

DELETE /workflows.php?id={id}

Delete a workflow.

POST /workflows.php?action=trigger&id={id}

Manually trigger a workflow.

GET /workflows.php?action=history

Get workflow execution history.

Monitoring

GET /monitoring/health.php

Get system health dashboard data.

GET /monitoring/collectors.php

Get collector health and sync status.

GET /monitoring/alerts.php

List active monitoring alerts.

POST /monitoring/alerts.php?action=acknowledge&id={id}

Acknowledge an alert.

Admin Operations

GET /admin/activity-log.php

Get admin activity log.

Query Parameters:

GET /admin/error-log.php

Get application error log (ops tenant only).

GET /job-types.php

Get available ticket job types/categories.

GET /departments.php

List departments.

GET /tech-status.php

Get technician statuses.

Bulk Operations

POST /bulk/tickets.php

Perform bulk operations on tickets.

Request:

{
  "action": "assign",
  "ticket_ids": [1042, 1043, 1044],
  "assigned_to": 8
}

Supported actions: assign, close, update_priority, update_status, delete

POST /bulk/assets.php

Perform bulk operations on assets.

POST /bulk/contacts.php

Perform bulk import/update of contacts.

Webhooks

GET /webhooks.php

List configured webhooks.

POST /webhooks.php

Register a new webhook.

Request:

{
  "url": "https://your-app.com/webhooks/valethon",
  "events": ["ticket.created", "ticket.closed", "asset.discovered"],
  "secret": "your_webhook_secret",
  "active": true
}

PUT /webhooks.php?id={id}

Update webhook configuration.

DELETE /webhooks.php?id={id}

Remove a webhook.

Webhook Events

Search

GET /search.php

Universal search across all entity types.

Query Parameters:

Response (200):

{
  "success": true,
  "data": {
    "tickets": [
      { "ticket_id": 1042, "subject": "Printer not working", "score": 0.95 }
    ],
    "assets": [
      { "asset_id": 200, "machine_name": "HP LaserJet Pro", "score": 0.85 }
    ],
    "total": 2
  }
}

Permissions Reference

API Key Module Permissions

For the Helpdesk API, see Helpdesk API Reference.

For the CRM integration API, see CRM API Reference.