API / Jobs

API

Jobs

Starting, polling and cancelling jobs, and downloading their output.

A job runs the engine on one binary with one set of settings. Jobs are queued and run in the background; you poll them until they finish.

Start a job#

http
POST /api/v1/jobs
Content-Type: application/json

Choose the settings in one of three ways:

json
{ "binary_id": "…" }
json
{ "binary_id": "…", "profile_id": "…" }
json
{ "binary_id": "…", "tool": "protect", "settings": { "function_timeout": 300 } }

With neither a profile nor settings, the tool's defaults are used. Settings you leave out take their default. A profile and settings can't be combined.

To choose functions without a profile, add targets and functions as in a profile:

json
{ "binary_id": "…", "targets": "listed", "functions": [{ "match": "Aes256*" }] }

Function rules#

When a job has function rules (its own or its profile's), they are matched against the binary's functions when you submit it, and the job keeps the result: changing the profile later doesn't change what the job protects. This needs the binary's analysis:

  • While it is still running, submitting returns 409; try again shortly.
  • If it failed, or the rules select no function at all, you get 422 saying why.
  • A rule that matches nothing isn't an error, since a function can be renamed or inlined away between builds. The job gets a RULE_NO_MATCH warning naming the rule.

The job's config.functions records how the functions were chosen:

json
"functions": {
  "targets": "listed",
  "rules": [{ "match": "Aes256*", "settings": { "protection": "none" } }, { "match": "Missing" }],
  "matches": [3, 0],
  "protected": 3,
  "total": 96,
  "groups": [{ "rule": 0, "settings": { "protection": "none" } }]
}

matches counts, per rule, the functions it matched. protected is how many the job protects, of the binary's total. groups are the different ways the protected functions were chosen: the rule that decided (absent under all when no rule matched) and the settings they get over the job's, merged from every rule that matched. Without rules there is no functions: every function is protected with the job's settings.

Response: 201 Created with {"job": { … }, "duplicate": false}.

Duplicate submissions#

If the same binary already has a job queued or running with exactly the same tool and settings, and selecting the same functions, you get that job back with 200 OK and "duplicate": true instead of a second job. Retrying a request after a network error therefore never runs the work twice. Once that job has finished, the same request starts a new one.

Job status#

http
GET /api/v1/jobs/{id}
json
{
  "id": "01a19951-b23f-775b-92a4-ef2d8019153e",
  "status": "succeeded",
  "binary_id": "01a19951-b0aa-7e58-ad41-ebd534d7a436",
  "binary_name": "app.exe",
  "binary_purged": false,
  "profile_id": "01a19951-b1cd-7cb3-884a-6410f326081f",
  "profile_name": "release",
  "tool": "protect",
  "config": { "tool": "protect", "schema_version": 1, "settings": { … } },
  "engine_version": "1.4.0",
  "error": null,
  "progress": null,
  "stats": { "functions_total": 290, "functions_protected": 285, "functions_skipped": 5 },
  "diagnostic_counts": { "error": 5, "warning": 9, "info": 2 },
  "diagnostics_truncated": false,
  "queued_at": "2026-11-01T22:53:50Z",
  "started_at": "2026-11-01T22:53:50Z",
  "finished_at": "2026-11-01T22:53:51Z",
  "expires_at": "2026-11-08T22:53:51Z",
  "purged_at": null,
  "artifacts": [
    {
      "id": "01a19951-b530-75a2-ba44-158b3f1a294f",
      "kind": "output",
      "filename": "app.protected.exe",
      "size": 200704,
      "sha256": "…",
      "expires_at": "2026-11-08T22:53:51Z",
      "download_url": "/api/v1/jobs/01a19951-…/artifacts/01a19951-…/download"
    }
  ]
}
status Meaning
queued Waiting for a worker.
running The engine is working on it. progress shows the current phase and how far it got.
succeeded Finished, and the output passed validation. Check diagnostic_counts.error: functions that couldn't be protected are reported as errors but don't fail the job unless the tool's settings say so.
failed Finished without output. error says why.
canceled Canceled before it finished.

Other fields worth knowing:

  • config is the exact tool, settings and function selection the job ran with, frozen when it was submitted.
  • profile_name is the profile's name at submit time; it stays even if the profile is renamed or deleted.
  • stats is reported by the engine when it finishes. Its keys may change between engine versions.
  • artifacts is only included when you get a single job.

Poll every few seconds. A typical job finishes in seconds; the limit is ten minutes.

Function results#

http
GET /api/v1/jobs/{id}/functions?status=kept_original&q=Aes*&after=0x1620&limit=1000

What happened to each function, once the engine has decided:

json
{
  "status": "succeeded",
  "counts": { "protected": 95, "kept_original": 1, "failed": 0 },
  "functions": [
    { "rva": "0x1620", "name": "Aes256EncryptBlock", "status": "protected", "protection": "virtualize", "ms": 840 },
    { "rva": "0x1000", "name": "Aes256Init", "status": "protected", "protection": "none", "requested": "virtualize",
      "reason": { "code": "XFORM_DOWNGRADED", "message": "…" } },
    { "rva": "0x19F0", "name": "Aes256DecryptBlock", "status": "kept_original",
      "reason": { "code": "LIFT_FRAME_UNPLACED", "message": "The function's stack frame could not be analysed, so it keeps its original code." } }
  ],
  "next_after": null
}
  • status is protected, kept_original (left as it was, so the output still works) or failed (only when the job's settings fail it on a function error).
  • protection, for a protected function, is what it got, such as virtualize. When that is less than it asked for, requested says what that was: a function that fails one of the engine's checks once virtualized is compiled again without protection, with an XFORM_DOWNGRADED error as its reason.
  • reason is the function's most severe diagnostic, when it has one: for a function that wasn't protected, why.
  • name comes from the binary's analysis, so with a .map it is the real name rather than sub_1620.
  • All parameters are optional. status filters; q searches names as in the function list, or finds an address such as 0x1620; counts follow the search. Pages are in RVA order: pass next_after back as after for the next one. limit defaults to 1000 and can be at most 5000.
  • Results arrive as the engine finishes functions, and are deleted with the diagnostics when the job is purged (410).

List jobs#

http
GET /api/v1/jobs?binary_id={id}&limit=50

Returns {"jobs": [ … ]}, newest first. Both parameters are optional; limit defaults to 50 and can be at most 200.

Cancel#

http
POST /api/v1/jobs/{id}/cancel

Stops a queued or running job and returns 204 No Content. A job that has already finished returns 409.

Download the output#

http
GET /api/v1/jobs/{id}/output

Returns the protected binary, with a Content-Disposition header naming it (app.protected.exe). A job without output (failed or canceled) returns 404; one whose files have expired returns 410.

Each artifact can also be fetched by its own download_url.