Jobs API - xyOps

Overview

Jobs represent individual executions of events. Use these endpoints to fetch job details, monitor progress, abort running jobs, and manage job history.

Get Active Jobs

GET /api/app/get_active_jobs/v1 Get all active jobs with optional search criteria, pagination, and sorting.

Parameters

state

string

Filter by state: queued or active

event

string

Filter by event ID

offset

number

Pagination offset (default: 0)

limit

number

Results per page (default: all)

sort_by

string

Sort field (default: started)

sort_dir

number

Sort direction: -1 descending, 1 ascending

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-server.com/api/app/get_active_jobs/v1?state=active&limit=50"

Response

{
  "code": 0,
  "rows": [
    {
      "id": "jabc123",
      "event": "event100",
      "state": "active",
      "progress": 0.5,
      "cpu": 25.5,
      "mem": 128000000
    }
  ],
  "list": { "length": 1 }
}

Get Job

GET /api/app/get_job/v1 Get detailed information about a single job (running or completed).

Parameters

string

required

Job ID to fetch

remove

array

Optional array of field names to exclude from response

Response

job

object

Complete job object with all details

token

string

Download token for accessing job log

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-server.com/api/app/get_job/v1?id=jabc123"

Response

{
  "code": 0,
  "token": "abc123def456",
  "job": {
    "id": "jabc123",
    "event": "event100",
    "state": "complete",
    "code": 0,
    "description": "Success",
    "started": 1234567890,
    "completed": 1234567900,
    "elapsed": 10,
    "cpu": { "total": 15.5 },
    "mem": { "max": 128000000 },
    "log_file_size": 4096
  }
}

Get Multiple Jobs

POST /api/app/get_jobs/v1 Fetch information about multiple jobs in a single request.

Parameters

ids

array

required

Array of job IDs to fetch

verbose

boolean

If true, include full details (default: false returns pruned data)

Example

cURL

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

Abort Job

POST /api/app/abort_job/v1 Abort a running job. Requires the abort_jobs privilege.

Parameters

string

required

Job ID to abort

Example

cURL

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

Response

{
  "code": 0
}

Resume Job

POST /api/app/resume_job/v1 Resume a suspended job. Requires the run_jobs privilege.

Parameters

string

required

Job ID to resume

params

object

Optional parameters to merge into job

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "jabc123",
    "params": {"continue": true}
  }' \
  https://your-server.com/api/app/resume_job/v1

Delete Job

POST /api/app/delete_job/v1 Permanently delete a completed job including log and files. Requires the delete_jobs privilege.

Parameters

string

required

Job ID to delete

Example

cURL

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

Deletions are permanent and cannot be undone.

Update Job

POST /api/app/update_job/v1 Update a running or completed job. This is an admin-only API that allows direct modification of job properties.

Parameters

string

required

Job ID to update

...

any

Any job properties to update

Example

cURL

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

Manage Job Tags

POST /api/app/manage_job_tags/v1 Update tags for a completed job. Requires the tag_jobs privilege.

Parameters

string

required

Job ID

Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "id": "jabc123",
    "tags": ["production", "critical"]
  }' \
  https://your-server.com/api/app/manage_job_tags/v1

Get Job Log

GET /api/app/get_job_log/v1 Fetch the plain text log for a job (gzip compressed).

Parameters

string

required

Job ID

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-server.com/api/app/get_job_log/v1?id=jabc123" \
  | gunzip

Download Job Log

GET /api/app/download_job_log/v1 Download job log file with token authentication (no session/API key required).

Parameters

string

required

Job ID

string

required

Download token from get_job response

Example

cURL

curl "https://your-server.com/api/app/download_job_log/v1?id=jabc123&t=TOKEN" \
  -o job.log.gz

Stream Job

GET /api/app/stream_job/v1 Stream real-time job updates via Server-Sent Events (SSE).

Parameters

string

required

Job ID to stream

token

string

Optional stream token (for magic link authentication)

Example

cURL

curl -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  "https://your-server.com/api/app/stream_job/v1?id=jabc123"

Event Stream Format

event: start
data: {}

event: update
data: {"id":"jabc123","state":"active","progress":0.25,"cpu":15.5}

event: update  
data: {"progress":0.5,"mem":128000000}

event: update
data: {"code":0,"description":"Success","completed":1234567900}

event: end
data: {}

The stream automatically closes when the job completes.

Flush Event Queue

POST /api/app/flush_event_queue/v1 Flush all queued jobs for an event without triggering completion actions. Requires the abort_jobs privilege.

Parameters

string

required

Event ID to flush queue for

Response

count

number

Number of jobs removed from queue

Example

cURL

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

Overview

Endpoints

Documentation Index

​Overview

​Get Active Jobs

​Parameters

​Example

​Get Job

​Parameters

​Response

​Example

​Get Multiple Jobs

​Parameters

​Example

​Abort Job

​Parameters

​Example

​Resume Job

​Parameters

​Example

​Delete Job

​Parameters

​Example

​Update Job

​Parameters

​Example

​Manage Job Tags

​Parameters

​Example

​Get Job Log

​Parameters

​Example

​Download Job Log

​Parameters

​Example

​Stream Job

​Parameters

​Example

​Event Stream Format

​Flush Event Queue

​Parameters

​Response

​Example

Build docs developers (and LLMs) love

Overview

Get Active Jobs

Parameters

Example

Get Job

Parameters

Response

Example

Get Multiple Jobs

Parameters

Example

Abort Job

Parameters

Example

Resume Job

Parameters

Example

Delete Job

Parameters

Example

Update Job

Parameters

Example

Manage Job Tags

Parameters

Example

Get Job Log

Parameters

Example

Download Job Log

Parameters

Example

Stream Job

Parameters

Example

Event Stream Format

Flush Event Queue

Parameters

Response

Example