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#
POST /api/v1/jobs
Content-Type: application/json
Choose the settings in one of three ways:
{ "binary_id": "…" }
{ "binary_id": "…", "profile_id": "…" }
{ "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:
{ "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
422saying 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_MATCHwarning naming the rule.
The job's config.functions records how the functions were chosen:
"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#
GET /api/v1/jobs/{id}
{
"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:
configis the exact tool, settings and function selection the job ran with, frozen when it was submitted.profile_nameis the profile's name at submit time; it stays even if the profile is renamed or deleted.statsis reported by the engine when it finishes. Its keys may change between engine versions.artifactsis 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#
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:
{
"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
}
statusisprotected,kept_original(left as it was, so the output still works) orfailed(only when the job's settings fail it on a function error).protection, for a protected function, is what it got, such asvirtualize. When that is less than it asked for,requestedsays what that was: a function that fails one of the engine's checks once virtualized is compiled again without protection, with anXFORM_DOWNGRADEDerror as itsreason.reasonis the function's most severe diagnostic, when it has one: for a function that wasn't protected, why.namecomes from the binary's analysis, so with a.mapit is the real name rather thansub_1620.- All parameters are optional.
statusfilters;qsearches names as in the function list, or finds an address such as0x1620;countsfollow the search. Pages are in RVA order: passnext_afterback asafterfor the next one.limitdefaults 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#
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#
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#
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.