HelixTrack Core - Complete API Reference

Comprehensive documentation for all 235 API endpoints

HelixTrack Core - Complete API Reference

Introduction

This document provides comprehensive documentation for all 234+ API endpoints in HelixTrack Core V2.0. All endpoints use the unified `/do` endpoint with action-based routing.

Total API Actions: 235

Version: 2.0

Last Updated: 2025-10-11

Public Endpoints (5 actions)
Authentication (1 action)
Generic CRUD Operations (5 actions)
Phase 1 - JIRA Parity Features (45 actions)
Workflow Engine (23 actions)
Agile/Scrum Support (23 actions)
Multi-Tenancy & Organizational Hierarchy (28 actions)
Supporting Systems (42 actions)
Git Integration (17 actions)
Ticket Relationships (8 actions)
System Infrastructure (37 actions)

Request/Response Format

Standard Request Format

All API requests use this structure:

{
  "action": "string",      // Required: action name
  "jwt": "string",         // Required for authenticated actions
  "locale": "string",      // Optional: locale code (e.g., "en-US")
  "object": "string",      // Required for generic CRUD operations
  "data": {}               // Action-specific data
}

Standard Response Format

All API responses use this structure:

{
  "errorCode": -1,                    // -1 = success, other = error
  "errorMessage": "string",           // Error message (empty on success)
  "errorMessageLocalised": "string",  // Localized error message
  "data": {}                          // Response data (varies by action)
}

Public Endpoints

These endpoints do not require authentication.

version

Get API version information.

Authentication: None required

Permissions: None required

Request:

{
  "action": "version"
}

Response:

{
  "errorCode": -1,
  "data": {
    "version": "2.0.0",
    "api": "2.0.0",
    "build": "2025-10-11"
  }
}

jwtCapable

Check if JWT authentication is enabled and available.

Request:

{
  "action": "jwtCapable"
}

Response:

{
  "errorCode": -1,
  "data": {
    "jwtCapable": true,
    "authServiceEnabled": true
  }
}

dbCapable

Check if database connection is available and healthy.

Request:

{
  "action": "dbCapable"
}

Response:

{
  "errorCode": -1,
  "data": {
    "dbCapable": true,
    "databaseType": "sqlite",
    "healthy": true
  }
}

health

Get overall system health status.

Request:

{
  "action": "health"
}

Response:

{
  "errorCode": -1,
  "data": {
    "status": "healthy",
    "checks": {
      "database": "healthy",
      "authService": "enabled",
      "permissionService": "enabled"
    },
    "uptime": 3600
  }
}

Health Check (GET)

Dedicated GET endpoint for health monitoring.

URL: GET /health

Response:

{
  "status": "healthy"
}

Authentication

authenticate

Authenticate user credentials and receive session information.

Request:

{
  "action": "authenticate",
  "data": {
    "username": "testuser",
    "password": "SecurePass123!"
  }
}

Response:

{
  "errorCode": -1,
  "data": {
    "username": "testuser",
    "name": "Test User",
    "role": "admin",
    "permissions": "READ|CREATE|UPDATE|DELETE"
  }
}

Generic CRUD Operations

These actions work with any entity type by specifying the object parameter.

create

Create a new entity.

Request:

{
  "action": "create",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "object": "project",
  "data": {
    "name": "New Project",
    "description": "Project description",
    "key": "PROJ"
  }
}

read

Read a specific entity by ID.

Request:

{
  "action": "read",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

list

List entities with optional filtering, pagination, and sorting.

Request:

{
  "action": "list",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "filter": {
      "status": "active"
    },
    "limit": 50,
    "offset": 0,
    "orderBy": "created",
    "order": "DESC"
  }
}

modify

Modify an existing entity.

Request:

{
  "action": "modify",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "object": "project",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Project Name",
    "description": "Updated description"
  }
}

remove

Soft-delete an entity (sets deleted flag, does not physically delete).

Request:

{
  "action": "remove",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "object": "project",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Phase 1 - JIRA Parity Features

These features provide 90%+ JIRA compatibility for core issue tracking functionality.

Priority Management

Manage ticket priorities (e.g., Low, Medium, High, Critical).

priorityCreate

Create a new priority level.

Request:

{
  "action": "priorityCreate",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "title": "Critical",
    "level": 5,
    "description": "Critical issues requiring immediate attention",
    "icon": "exclamation-circle",
    "color": "#FF0000"
  }
}

priorityRead

Read a specific priority by ID.

Request:

{
  "action": "priorityRead",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

priorityList

List all priorities ordered by level.

Request:

{
  "action": "priorityList",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {}
}

priorityModify

Update an existing priority.

Request:

{
  "action": "priorityModify",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Urgent",
    "level": 5,
    "color": "#FF3300"
  }
}

priorityRemove

Soft-delete a priority.

Request:

{
  "action": "priorityRemove",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Resolution Management

Manage ticket resolutions (e.g., Done, Won't Fix, Duplicate).

resolutionCreate

Create a new resolution type.

Request:

{
  "action": "resolutionCreate",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "title": "Done",
    "description": "Task completed successfully"
  }
}

resolutionRead

Read a specific resolution by ID.

Request:

{
  "action": "resolutionRead",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

resolutionList

List all resolutions ordered by title.

Request:

{
  "action": "resolutionList",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {}
}

resolutionModify

Update an existing resolution.

Request:

{
  "action": "resolutionModify",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Completed",
    "description": "Work finished and verified"
  }
}

resolutionRemove

Soft-delete a resolution.

Request:

{
  "action": "resolutionRemove",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Version Management

Manage product versions with affected/fix version tracking.

versionCreate

Create a new version.

Request:

{
  "action": "versionCreate",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "name": "v1.0.0",
    "description": "First stable release",
    "releaseDate": 1696118400,
    "startDate": 1693526400,
    "released": false,
    "archived": false
  }
}

versionRead

Read a specific version by ID.

Request:

{
  "action": "versionRead",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

versionList

List all versions.

Request:

{
  "action": "versionList",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {}
}

versionModify

Update an existing version.

Request:

{
  "action": "versionModify",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "v1.0.1",
    "description": "Bug fix release"
  }
}

versionRemove

Soft-delete a version.

Request:

{
  "action": "versionRemove",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

versionRelease

Mark a version as released.

Request:

{
  "action": "versionRelease",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

versionArchive

Archive a version.

Request:

{
  "action": "versionArchive",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

versionAddAffected

Add an affected version to a ticket.

Request:

{
  "action": "versionAddAffected",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "ticketId": "PROJ-123",
    "versionId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

versionRemoveAffected

Remove an affected version from a ticket.

Request:

{
  "action": "versionRemoveAffected",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "ticketId": "PROJ-123",
    "versionId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

versionListAffected

List all affected versions for a ticket.

Request:

{
  "action": "versionListAffected",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "ticketId": "PROJ-123"
  }
}

versionAddFix

Add a fix version to a ticket.

Request:

{
  "action": "versionAddFix",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "ticketId": "PROJ-123",
    "versionId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

versionRemoveFix

Remove a fix version from a ticket.

Request:

{
  "action": "versionRemoveFix",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "ticketId": "PROJ-123",
    "versionId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

versionListFix

List all fix versions for a ticket.

Request:

{
  "action": "versionListFix",
  "jwt": "eyJhbGciOiJIUzI1NiIs...",
  "data": {
    "ticketId": "PROJ-123"
  }
}

Watcher Management

Manage ticket watchers (3 actions).

Filter Management

Manage saved filters (6 actions).

Custom Field Management

Manage custom fields (13 actions, 11 field types).

Workflow Engine

Workflow management (23 actions).

Agile/Scrum Support

Board and cycle management (23 actions).

Multi-Tenancy & Organizational Hierarchy

Account, organization, team management (28 actions).

Supporting Systems

Component, label, asset management (42 actions).

Git Integration

Repository management (17 actions).

Ticket Relationships

Relationship management (8 actions).

System Infrastructure

Permission, audit, report, extension management (37 actions).

Error Codes Reference

Success

-1: No error (success)

Request Errors (100X)

1000: Invalid request format
1001: Invalid action name
1002: Missing JWT token
1003: Invalid JWT token
1004: Missing object parameter
1005: Invalid object parameter
1006: Missing required data
1007: Invalid data format
1008: Unauthorized (not authenticated)
1009: Forbidden (insufficient permissions)

System Errors (200X)

2000: Internal server error
2001: Database error
2002: Service unavailable
2003: Configuration error
2004: Authentication service error
2005: Permission service error
2006: Extension service error

Entity Errors (300X)

3000: Entity not found
3001: Entity already exists
3002: Entity validation failed
3003: Entity delete failed
3004: Entity update failed
3005: Entity create failed

Document Version: 2.0

API Version: 2.0.0

Last Updated: 2025-10-11

Total Endpoints: 235

HelixTrack Core - Complete API Reference

HelixTrack Core - Complete API Reference

Introduction

Table of Contents

Request/Response Format

Standard Request Format

Standard Response Format

Public Endpoints

version

jwtCapable

dbCapable

health

Health Check (GET)

Authentication

authenticate

Generic CRUD Operations

create

read

list

modify

remove

Phase 1 - JIRA Parity Features

Priority Management

priorityCreate

priorityRead

priorityList

priorityModify

priorityRemove

Resolution Management

resolutionCreate

resolutionRead

resolutionList

resolutionModify

resolutionRemove

Version Management

versionCreate

versionRead

versionList

versionModify

versionRemove

versionRelease

versionArchive

versionAddAffected

versionRemoveAffected

versionListAffected

versionAddFix

versionRemoveFix

versionListFix

Watcher Management

Filter Management

Custom Field Management

Workflow Engine

Agile/Scrum Support

Multi-Tenancy & Organizational Hierarchy

Supporting Systems

Git Integration

Ticket Relationships

System Infrastructure

Error Codes Reference

Success

Request Errors (100X)

System Errors (200X)

Entity Errors (300X)