Jobs API

The jobs API lets an authorized client create, schedule and manage asynchronous jobs — background operations (validation, indexing, pseudonymization, LRS pull/push, clearing, deletions, seeding, the conformance test-suite, …) that run detached from the request, either once or on a recurring schedule. Authentication, value/field types and error responses are common to all TRAX APIs.

Every job type exposes the same set of endpoints and the same scheduling body — only the job's own parameters (and, for a few types, the required permission) differ. That shared shape is documented once in The job pattern; the per-type differences are in Job types.

Contents: validation · indexing · pseudo · pull · push · clearing · agent-deletion · seeding · testsuite · logs-deletion · stores-deletion · cmi5-tokens-deletion

Getting access

• Enable the API. This API is gated by the JOBS_API feature toggle (Settings → App). When off, the machine-token API is unavailable (the console UI is unaffected).
• Client permission. The calling client must have the tasks/all permission enabled (Clients → edit → Permissions) — this covers validation, indexing, pseudo, pull, push, clearing, agent-deletion, seeding and testsuite. logs-deletion additionally needs logging/all; stores-deletion and cmi5-tokens-deletion additionally need access/all. Authentication is HTTP Basic — see Authentication.
• Base path. Copy your client's endpoint (…/clients/{client}) from the Clients page (the ⓘ info button) and append the jobs/… paths below.

The job pattern

For a job {type} (one of the route segments in Job types), the endpoints are:

POST   /trax/api/gateway/clients/{client}/jobs/{type}          create / schedule a job
GET    /trax/api/gateway/clients/{client}/jobs/{type}          list jobs of this type
DELETE /trax/api/gateway/clients/{client}/jobs/{type}          clear (delete all) jobs of this type
PUT    /trax/api/gateway/clients/{client}/jobs/{type}/{job}    update a job
GET    /trax/api/gateway/clients/{client}/jobs/{type}/{job}    find one job
DELETE /trax/api/gateway/clients/{client}/jobs/{type}/{job}    delete one job
GET    /trax/api/gateway/clients/{client}/jobs/{type}/{job}/logs   read a job's run logs

Path segments:

• {client} — your API client id.
• {type} — the job type (route segment), one of the sections in Job types.
• {job} — the id of a specific job.

Create / update behaviour

POST and PUT take a JSON body of the type's own body params (see Job types) plus the shared scheduling fields. Both validate the merged rules and, on success, persist the job and return 204 No Content with an empty body — the job is queued to run asynchronously (immediately or at its next scheduled time), so there is no result, and no job id, in the response. Retrieve the created jobs and their outcome with GET afterwards.

Per-store fan-out

Most job types accept an optional store param. When it is omitted (for the types whose store rule is nullable), the job is fanned out across every ready store — one job is created per store. When store is supplied, a single job is created for that store. Some types create several jobs per store regardless (e.g. one job per selected index/database); this is noted per type.

Scheduling fields

Every POST / PUT body accepts these shared fields (merged with the type's own params). repeat selects the cadence; the other fields are required only for the cadences noted.

Name	Type	Description
repeat	enum (required)	Cadence. One of now, on, everyMinute, hourlyAt, dailyAt, weeklyOn, monthlyOn, yearlyOn.
date	ISO-8601 date-time	The run date/time. Required when repeat = on. Format YYYY-MM-DD HH:MM.
time	string HH:MM or now	Time of day. Required when repeat is dailyAt, weeklyOn, monthlyOn or yearlyOn.
minute	integer 0–59	Minute of the hour. Required when repeat = hourlyAt.
week_day	integer 1–7	Day of week. Required when repeat = weeklyOn.
month_day	integer 1–31	Day of month. Required when repeat is monthlyOn or yearlyOn.
month	integer 1–12	Month of year. Required when repeat = yearlyOn.
replay	boolean	Re-run a completed job (replay flag).

Response

• POST / PUT / DELETE (delete, clear): 204 No Content, empty body.
• GET (list): 200 with { "data": [ /* array of jobs */ ] }.
• GET (find): 200 with { "data": { /* one job */ } }.
• GET (logs): 200 with { "data": [ /* array of run-log entries */ ] }.

A job record carries its scheduling fields (repeat, date, time, minute, week_day, month_day, month), its type, service, store, client, name, the type-specific settings object, and its run state: running, ran, success, status, feedback, started_at, completed_at. Each log entry (event, success, feedback, data) records one run event. Error responses follow the shared model.

Job types

Each type's body is its params below merged with the shared scheduling fields. Where a type has an until cutoff, it is one of now, date, 1_hour, 1_day, 1_week, 1_month, 1_year; when it is date, until_date (an ISO-8601 date-time) is required.

validation

Re-validates stored statements. Fans out per store when store is omitted.

Name	Type	Description
clear	boolean	Required. Also delete the statements found invalid.
store	string	Optional; omit to fan out across all ready stores.

indexing

Rebuilds catalogue / vocabulary indexes — one job per selected index per store. Fans out per store when store is omitted.

Name	Type	Description
indexes	array	Required. One or more of activities, agents, verbs, activity-types, activity-ids, agent-ids, document-ids.
store	string	Optional; omit to fan out across all ready stores.

pseudo

Pseudonymizes statement actors up to the cutoff. Fans out per store when store is omitted.

Name	Type	Description
until	enum	Required. The cutoff (see above).
until_date	ISO-8601 date-time	Required when until = date.
store	string	Optional; omit to fan out across all ready stores.

pull

Pulls xAPI data from a remote connection into the store. For an LRS connection, service is forced to statements and xAPI-version compatibility is checked.

Name	Type	Description
service	enum	Required. One of all, statements, activities, agents, activity-profiles, agent-profiles, states.
until	enum	Required. The cutoff (see above).
until_date	ISO-8601 date-time	Required when until = date.
connection	integer	Required. An existing connection id.
validate_statements	boolean	Required for service all / statements.
check_conflicts	boolean	Required for service all / statements.
void_statements	boolean	Required for service all / statements.
update_activities	boolean	Required for service all / statements.
update_agents	boolean	Required for service all / statements.
update_activity_ids	boolean	Required for service all / statements / activities.
update_agent_ids	boolean	Required for service all / statements / agents.
update_vocab	boolean	Required.
authority_name	string	Required. Authority account name applied to pulled statements.
authority_homepage	URL	Required. Authority account homePage.
store	string	Required.

push

Pushes xAPI data from the store to a remote connection. For an LRS connection, service is forced to statements and raw / sync_updates are forced.

Name	Type	Description
service	enum	Required. Same set as pull.
until	enum	Required. The cutoff (see above).
until_date	ISO-8601 date-time	Required when until = date.
connection	integer	Required. An existing connection id.
raw	boolean	Required. Push the raw statements.
sync_updates	boolean	Required unless service = statements.
pseudonymize_statements	boolean	Required for service all / statements.
store	string	Required.

clearing

Deletes data from the selected service databases up to the cutoff — one job per selected service per store. Fans out per store when store is omitted.

Name	Type	Description
services	array	Required. One or more of statements, activities, agents, activity-profiles, agent-profiles, states, vocab.
until	enum	Required. The cutoff (see above).
until_date	ISO-8601 date-time	Required when until = date.
store	string	Optional; omit to fan out across all ready stores.

agent-deletion

Deletes an agent — or a whole person's agents — and their data across statements, agents, agent-profiles and states. Fans out per store when store is omitted.

Name	Type	Description
agent	Agent IFI	Required. The agent to delete.
person	boolean	Required. Delete the whole person (all their agents), not just this one agent.
store	string	Optional; omit to fan out across all ready stores.

seeding

Seeds the store with test / demo data from a named config.

Name	Type	Description
config	string	Optional; the seeding config name (defaults to default).
store	string	Required.

testsuite

Runs the xAPI conformance test-suite against a store / client.

Name	Type	Description
version	enum	Required. 1.0.3 or 2.0.0.
section	string	Optional; a specific test section.
store	string	Required.
client	string	Required.

logs-deletion

Deletes log entries up to a level and cutoff. Fans out per store when store is omitted. (also requires the logging/all permission)

Name	Type	Description
max_level	integer (0–7)	Required. Highest severity level to delete.
until	enum	Required. The cutoff (see above).
until_date	ISO-8601 date-time	Required when until = date.
store	string	Optional; omit to fan out across all ready stores.

stores-deletion

Deletes an entire store. Refused when only one ready store remains. (also requires the access/all permission)

Name	Type	Description
store_id	integer	Required. An existing store id (not the primary store 1).

cmi5-tokens-deletion

Deletes expired cmi5 auth tokens up to the cutoff. Fans out per store when store is omitted. (also requires the access/all permission)

Name	Type	Description
until	enum	Required. One of now, 1_hour, 1_day, 1_week.
store	string	Optional; omit to fan out across all ready stores.

Example: schedule and inspect a job

Create a daily validation job at 02:00 for one store (the POST body merges the type params with the scheduling fields):

POST /trax/api/gateway/clients/{client}/jobs/validation

{
  "clear": true,
  "store": "default",
  "repeat": "dailyAt",
  "time": "02:00"
}

Response: 204 No Content — the job is persisted and will run asynchronously at the next scheduled time.

List the jobs of that type to get the created record(s) and their status:

GET /trax/api/gateway/clients/{client}/jobs/validation

{
  "data": [
    {
      "id": 42,
      "type": "validation",
      "service": "statements",
      "name": "Validate statements and remove invalid ones",
      "store": "default",
      "repeat": "dailyAt",
      "time": "02:00",
      "settings": { "clear": true },
      "running": false,
      "ran": false,
      "success": null,
      "status": null,
      "started_at": null,
      "completed_at": null
    }
  ]
}

Read a job's run logs with GET /trax/api/gateway/clients/{client}/jobs/validation/{job}/logs.