Helpdesk API Reference

The Valethon Helpdesk API enables end-user portals and integrations to interact with the support system. It provides ticket management, asset visibility, knowledge base access, AI chat, billing, and project tracking for authenticated helpdesk users.

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

Authentication

The Helpdesk API supports two authentication methods:

Session-Based Authentication

Standard browser session via cookies. Used by the Helpdesk SPA.

JWT Bearer Tokens

For programmatic access. Obtain tokens via the login endpoint and include them in subsequent requests.


Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token Lifecycle:

Access tokens expire after a configurable duration
Use the refresh endpoint to obtain new access tokens
Refresh tokens can be revoked on logout

Response Format

All responses return JSON with consistent structure:

Success:


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

Error:


{
  "error": "Description of the error"
}

Paginated:


{
  "tickets": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No Content (successful DELETE)
400	Bad Request (validation error)
401	Unauthorized (authentication required)
403	Forbidden (insufficient permissions or module disabled)
404	Not Found
500	Internal Server Error

Authentication Endpoints

POST /auth/login

Authenticate with email and password. Returns JWT tokens.

Request:


{
  "username": "user@company.com",
  "password": "secret"
}

Response (200):


{
  "success": true,
  "access_token": "eyJhbG...",
  "refresh_token": "dGhpcyBpc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "employee_number": 42,
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@company.com",
    "company_name": "Acme Corp"
  }
}

POST /auth/refresh

Exchange a refresh token for a new access token.

Request:


{
  "refresh_token": "dGhpcyBpc..."
}

Response (200):


{
  "success": true,
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600
}

GET /auth/session

Check current authentication status.

Response (200):


{
  "authenticated": true,
  "user": { ... }
}

POST /auth/logout

Destroy session and optionally revoke refresh token.

Request (optional):


{
  "refresh_token": "dGhpcyBpc..."
}

GET /auth/profile

Get the authenticated user's full profile.

Response (200):


{
  "employee_number": 42,
  "company_number": 1,
  "site_number": 5,
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane@company.com",
  "phone": "+1-555-0123",
  "department": "Engineering",
  "company_name": "Acme Corp",
  "site_name": "Main Office",
  "permissions": {
    "can_create_tickets": true,
    "can_view_assets": true,
    "can_view_billing": false
  }
}

PUT /auth/profile

Update the authenticated user's profile fields.

Request:


{
  "first_name": "Jane",
  "last_name": "Smith-Jones",
  "phone": "+1-555-9999"
}

POST /auth/change-password

Change the authenticated user's password.

Request:


{
  "current_password": "oldpass",
  "new_password": "newpass123!"
}

GET /auth/oauth/providers

Get enabled OAuth providers for social login.

Response (200):


{
  "success": true,
  "providers": [
    { "key": "google", "name": "Google", "icon": "google", "color": "#4285F4" },
    { "key": "microsoft", "name": "Microsoft", "icon": "microsoft", "color": "#00A4EF" }
  ]
}

GET /auth/oauth/authorize

Get OAuth authorization URL for a provider.

Query Parameters:

Parameter	Type	Required	Description
provider	string	Yes	`google`, `microsoft`, or `apple`
redirect_uri	string	No	Custom redirect URI

Ticket Management

GET /tickets

List tickets for the authenticated user.

Query Parameters:

Parameter	Type	Default	Description
status	string	all	`open`, `closed`, `in_progress`, `on_hold`, `all`
page	int	1	Page number
limit	int	20	Items per page (max 100)

Response (200):


{
  "tickets": [
    {
      "ticket_id": 1042,
      "ticket_number": 3018,
      "subject": "Printer not working",
      "description": "The main office printer shows offline...",
      "status": "open",
      "priority": 3,
      "job_type": "Hardware",
      "assigned_tech": 5,
      "created_at": "2026-03-10T14:30:00Z",
      "updated_at": "2026-03-11T09:15:00Z",
      "closed_at": null
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 45, "total_pages": 3 }
}

POST /tickets

Create a new support ticket.

Request:


{
  "subject": "VPN connection failing",
  "description": "Unable to connect to VPN since this morning...",
  "priority": 3,
  "job_type": "Network"
}

Response (201):


{
  "success": true,
  "ticket_id": 1043,
  "ticket_number": 3019,
  "subject": "VPN connection failing",
  "status": "open",
  "requires_approval": false
}

GET /tickets/{id}

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

Response (200):


{
  "ticket_id": 1042,
  "ticket_number": 3018,
  "subject": "Printer not working",
  "description": "...",
  "status": "open",
  "priority": 3,
  "job_type": "Hardware",
  "assigned_tech": 5,
  "created_at": "2026-03-10T14:30:00Z",
  "comments": [
    {
      "comment_id": 501,
      "comment": "I've checked the network cable...",
      "author_name": "Mike Tech",
      "is_internal": false,
      "created_at": "2026-03-10T15:00:00Z"
    }
  ],
  "asset": { "asset_id": 200, "machine_name": "HP LaserJet Pro" },
  "contracts": []
}

PUT /tickets/{id}

Update ticket fields (status, priority, subject, job type).

POST /tickets/{id}/comments

Add a comment to a ticket.

Request:


{
  "comment": "I've tried restarting the printer and the issue persists."
}

GET /tickets/pending-approval

List tickets pending manager approval. Requires manager role.

GET /tickets/approval-count

Get count of tickets pending approval (for UI badge).

Response (200):


{
  "is_manager": true,
  "pending_count": 3
}

POST /tickets/{id}/approve

Approve a pending ticket. Requires manager role.

POST /tickets/{id}/reject

Reject a pending ticket with reason. Requires manager role.

Request:


{
  "reason": "This request needs additional budget approval first."
}

GET /tickets/team

Get tickets for the authenticated user's team (manager only).

GET /tickets/search

Search tickets with advanced filters.

POST /tickets/bulk

Perform bulk operations on multiple tickets.

GET /tickets/export

Export tickets to file (CSV, PDF).

Employee Management

GET /employees

List employees for the company.

Query Parameters:

Parameter	Type	Description
page	int	Page number
per_page	int	Items per page
search	string	Search by name or email
status	string	Filter by status
department	string	Filter by department

GET /employees/{id}

Get employee details.

POST /employees

Create a new employee.

PUT /employees/{id}

Update employee information.

GET /employees/options

Get employee list for dropdown selectors.

GET /employees/template

Get template structure for creating employees.

POST /employees/import

Bulk import employees from CSV or JSON.

Manager Groups

Manager group endpoints require IT admin privileges.

GET /managers

List all manager groups.

GET /managers/{code}

Get manager group details.

POST /managers

Create a new manager group.

PUT /managers/{code}

Update a manager group.

DELETE /managers/{code}

Delete a manager group.

POST /managers/{code}/managers

Add a manager to a group.

DELETE /managers/{code}/managers/{employee_id}

Remove a manager from a group.

POST /managers/{code}/members

Add a member to a manager group.

DELETE /managers/{code}/members/{employee_id}

Remove a member from a manager group.

GET /managers/{code}/available-employees

Get employees available to add to a group.

Asset Management

Asset endpoints require authentication and asset read/edit permissions.

GET /assets

List assets the user has access to.

Query Parameters:

Parameter	Type	Description
page	int	Page number
per_page	int	Items per page
type	string	Filter by asset type
status	string	Filter by status
q	string	Search query
mine	boolean	Only user's assigned assets

GET /assets/{id}

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

POST /assets

Create a new asset. Requires asset edit permission.

PUT /assets/{id}

Update asset information.

DELETE /assets/{id}

Delete an asset.

POST /assets/{id}/ports

Add a network port to an asset.

PUT /assets/{id}/ports

Update port information.

DELETE /assets/{id}/ports

Delete a port.

POST /assets/{id}/credentials

Add login credentials to an asset.

PUT /assets/{id}/credentials/{login_id}

Update stored credentials.

DELETE /assets/{id}/credentials/{login_id}

Delete stored credentials.

GET /assets/{id}/licenses

Get licenses linked to an asset.

POST /assets/{id}/licenses

Link a license to an asset.

DELETE /assets/{id}/licenses/{license_id}

Unlink a license from an asset.

GET /assets/{id}/contracts

Get service contracts linked to an asset.

GET /assets/{id}/ip-addresses

Get IP addresses assigned to an asset.

GET /assets/options

Get assets for dropdown selectors.

GET /assets/template

Get template for creating assets.

POST /assets/import

Bulk import assets.

Chat & AI Assistant

POST /chat/start

Start a new chat session or resume an existing one.

Response (200):


{
  "chat_id": 101,
  "status": "active",
  "ticket_id": null,
  "started_at": "2026-03-13T10:00:00Z",
  "resumed": false,
  "messages": []
}

GET /chat/{id}/messages

Get chat message history.

Query Parameters:

Parameter	Type	Description
page	int	Page number
per_page	int	Messages per page
since	string	ISO timestamp, return messages after this time

POST /chat/{id}/messages

Send a message to the chat (processed by Val AI).

Request:


{
  "message": "My laptop won't connect to the Wi-Fi network"
}

Response (200):


{
  "message_id": 502,
  "sender_type": "user",
  "message": "My laptop won't connect to the Wi-Fi network",
  "created_at": "2026-03-13T10:05:00Z"
}

POST /chat/{id}/ticket

Create a ticket from the chat conversation.

POST /chat/{id}/request-agent

Request transfer to a human support agent.

POST /chat/{id}/end

End the chat session.

Knowledge Base

GET /kb/articles

Search and list knowledge base articles.

Query Parameters:

Parameter	Type	Description
page	int	Page number
per_page	int	Items per page
search	string	Full-text search query
category	string	Filter by category

GET /kb/articles/{id}

Get a single article with related entity links.

POST /kb/articles

Create a new KB article.

PUT /kb/articles/{id}

Update an existing KB article.

Billing

Billing endpoints require the Billing module to be enabled for the company.

GET /billing/invoices

List company invoices.

Query Parameters:

Parameter	Type	Description
page	int	Page number
per_page	int	Items per page
status	string	Filter by invoice status

GET /billing/invoices/{id}

Get invoice details with line items.

GET /billing/payments

List company payments.

GET /billing/proposals

List billing proposals.

GET /billing/proposals/{id}

Get proposal details.

POST /billing/proposals/{id}

Act on a proposal (accept, reject).

GET /billing/subscriptions

List active subscriptions.

GET /billing/statements

List billing statements.

Network & Infrastructure

GET /networks

List company networks.

GET /networks/{id}

Get network details with VLAN information.

GET /sites

List company sites and locations.

Inventory

GET /licenses

List software licenses for the company.

GET /contracts

List service contracts.

GET /domains

List registered domains.

Project Management

GET /projects

List company projects.

GET /projects/{project_id}

Get project details with phases, milestones, and punch list.

GET /projects/{project_id}/milestones

List milestones for a project.

GET /milestones/pending

List milestones pending approval (manager only).

GET /milestones/approval-count

Get count of milestones pending approval.

GET /milestones/{id}

Get milestone details.

POST /milestones/{id}/approve

Approve a milestone (manager only).

POST /milestones/{id}/reject

Reject a milestone with reason (manager only).

POST /milestones/{id}/request-info

Request additional information about a milestone.

GET /projects/{project_id}/punch-list

Get project punch list items.

POST /projects/{project_id}/punch-list

Submit punch list items.

POST /projects/{project_id}/punch-list/{item_id}/respond

Respond to punch list item feedback.

POST /projects/{project_id}/punch-list/{item_id}/attachments

Upload attachments to a punch list item.

Reporting

GET /reports/metrics

Get dashboard metrics and KPIs.

GET /reports

List available reports.

GET /reports/{id}

Get report configuration.

POST /reports

Create a new report.

PUT /reports/{id}

Update report configuration.

DELETE /reports/{id}

Delete a report.

POST /reports/{id}/run

Execute report and get results.

GET /reports/{id}/export

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

POST /reports/{id}/gsheet

Sync report to Google Sheets.

GET /reports/fields/{source}

Get available fields for report creation.

Search

GET /search

Universal search across all entities (tickets, assets, employees, KB articles).

GET /searches

List saved search queries.

POST /searches

Save a search query.

DELETE /searches/{id}

Delete a saved search.

Backup & Recovery

GET /backup/status

Get backup status and recent backups.

GET /backup/restore-requests

List data recovery requests.

POST /backup/restore-requests

Submit a data restoration request.

System Endpoints

GET /bootstrap

Called on SPA initialization. Returns tenant branding, user context, features, and OAuth providers. No authentication required.

GET /branding.css

Dynamically generated CSS with tenant branding colors. No authentication required.

GET /status

Get service outage status for the company.

GET /job-types

Get available job types (ticket categories).

GET /modules

Get enabled feature modules for the company.

Permissions Reference

Permission	Controls
`can_create_tickets`	Ticket creation
`asset_edit` (None/Read Only/Modify)	Asset access level
`ismgr`	Manager approval capabilities
`it_privileges`	IT admin features
Billing module	Access to billing endpoints

Rate Limiting

The API enforces rate limits per session/token. When exceeded, a 429 Too Many Requests response is returned. Standard limits apply per-tenant.

For the OpenAPI specification, see helpdesk-openapi.yaml.

For ServiceOS admin API documentation, see ServiceOS API Reference.

For CRM integration API documentation, see CRM API Reference.