Tickets API

Create and manage support tickets

Overview

The Tickets API provides endpoints for creating, updating, searching, and managing support tickets within xyOps.

Get Ticket

GET /api/app/get_ticket/v1

Load a single ticket by ID or ticket number.

Parameters

id · string

Ticket ID (either id or num required)

num · number

Ticket number (alternative to id)

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-server.com/api/app/get_ticket/v1?num=42"

Response

{
  "code": 0,
  "ticket": {
    "id": "t12345",
    "num": 42,
    "subject": "Server maintenance required",
    "status": "open",
    "type": "task",
    "username": "admin",
    "assignees": ["devops"],
    "created": 1234567890,
    "modified": 1234567890
  }
}

Get Multiple Tickets

POST /api/app/get_tickets/v1

Fetch information about multiple tickets.

Parameters

ids · array · required

Array of ticket IDs

verbose · boolean

If true, include full details including body and changes (default: false)

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "ids": ["t12345", "t67890"],
    "verbose": true
  }' \
  https://your-server.com/api/app/get_tickets/v1

Search Tickets

POST /api/app/search_tickets/v1

Search for tickets using query syntax.

Parameters

query · string

Search query (default: * for all)

offset · number

Pagination offset (default: 0)

limit · number

Results per page (default: 1)

sort_by · string

Sort field (default: _id)

sort_dir · number

Sort direction: -1 descending, 1 ascending

compact · boolean

If true, scrub verbose params from results

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "query": "status:open type:bug",
    "offset": 0,
    "limit": 50,
    "compact": true
  }' \
  https://your-server.com/api/app/search_tickets/v1

Response

{
  "code": 0,
  "rows": [
    {
      "id": "t12345",
      "num": 42,
      "subject": "Critical bug",
      "status": "open",
      "type": "bug"
    }
  ],
  "list": { "length": 1 }
}

Create Ticket

POST /api/app/create_ticket/v1

Create a new ticket. Requires the create_tickets privilege.

Parameters

subject · string · required

Ticket subject/title

body · string

Ticket description (Markdown supported)

type · string

Ticket type (e.g., task, bug, feature)

status · string

Status (default: open)

assignees · array

Array of assigned usernames

tags · array

Array of tag IDs

due · number

Due date as Unix timestamp

cc · array

Array of CC’d email addresses

template · string

Auto-generate body from template: job or alert

job · string

Job ID (when using template: "job")

alert · string

Alert invocation ID (when using template: "alert")

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "subject": "Server maintenance required",
    "body": "Need to update packages on production servers.",
    "type": "task",
    "status": "open",
    "assignees": ["devops"],
    "tags": ["production", "maintenance"]
  }' \
  https://your-server.com/api/app/create_ticket/v1

When using template: "job" or template: "alert", the ticket body is auto-generated from the corresponding job or alert data.

Update Ticket

POST /api/app/update_ticket/v1

Update an existing ticket. Requires the edit_tickets privilege. Supports sparse updates.

Parameters

id · string · required

Ticket ID to update

... · any

Any ticket properties to update (subject, status, assignees, etc.)

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "t12345",
    "status": "in_progress",
    "assignees": ["devops", "admin"]
  }' \
  https://your-server.com/api/app/update_ticket/v1

Add Ticket Change

POST /api/app/add_ticket_change/v1

Add a change (comment) to a ticket. Requires the edit_tickets privilege.

Parameters

id · string · required

Ticket ID

change · object · required

Change object with type and optional body

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "t12345",
    "change": {
      "type": "comment",
      "body": "Started working on this task."
    }
  }' \
  https://your-server.com/api/app/add_ticket_change/v1

Update Ticket Change

POST /api/app/update_ticket_change/v1

Update or delete a specific change in a ticket. Requires the edit_tickets privilege.

Parameters

id · string · required

Ticket ID

change_id · string · required

Change ID to update or delete

change · object

Updated change properties (omit if deleting)

delete · boolean

If true, delete the change

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "t12345",
    "change_id": "c123",
    "change": {
      "body": "Updated comment text."
    }
  }' \
  https://your-server.com/api/app/update_ticket_change/v1

Upload Ticket Files

POST /api/app/upload_user_ticket_files/v1

Upload files for a ticket. Requires the edit_tickets privilege.

Parameters

ticket · string · required

Ticket ID

save · boolean

If true, immediately attach files to ticket

Request Format

Use multipart/form-data with file fields.

Example

cURL

curl -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "ticket=t12345" \
  -F "save=true" \
  -F "file=@screenshot.png" \
  https://your-server.com/api/app/upload_user_ticket_files/v1

Response

{
  "code": 0,
  "files": [
    {
      "id": "f123",
      "filename": "screenshot.png",
      "path": "files/t12345/admin/abc123/screenshot.png",
      "size": 204800,
      "date": 1234567890
    }
  ]
}

Delete Ticket File

POST /api/app/delete_ticket_file/v1

Delete a file from a ticket. Requires the edit_tickets privilege.

Parameters

id · string · required

Ticket ID

path · string · required

File path to delete

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "t12345",
    "path": "files/t12345/admin/abc123/screenshot.png"
  }' \
  https://your-server.com/api/app/delete_ticket_file/v1

Delete Ticket

POST /api/app/delete_ticket/v1

Permanently delete a ticket. Requires the delete_tickets privilege.

Parameters

id · string · required

Ticket ID to delete

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"id": "t12345"}' \
  https://your-server.com/api/app/delete_ticket/v1

Deletions are permanent. This also removes the ticket from any associated jobs and alerts.

Ticket Types

Common ticket types:

Type	Description
task	General task or to-do
bug	Software defect
feature	Feature request
question	Question or inquiry
incident	Service incident

Ticket Statuses

Common ticket statuses:

Status	Description
draft	Not yet published
open	Open and unassigned
in_progress	Currently being worked on
on_hold	Waiting for external input
resolved	Completed successfully
closed	Archived/closed

Change Types

Ticket changes track history:

Type	Description
change	System-generated change record
comment	User comment
status	Status change
assignment	Assignment change

Ticket body and comments support Markdown formatting.