Report a completed direct-VM job's cache outcome

POST/api/jobs/{job_id}/vm-cache-report

reportJobVmCache

Runner-protocol route. A direct-VM agent whose claim said `accepts_vm_cache_report` completes the job at its guest's outcome and sends the job's cache report here once its VM is torn down (ADR 0146, amended 2026-10-27). The body is the `vm_cache` a completion would carry, checked and ingested under the same rules. Accepted only from the runner that executed the job, only once the job is terminal, once per job and within 10 minutes of its finish: a repeat, or a report that fails the checks, is 204 and changes nothing. A job this runner did not execute, or no such job, is 403; a job it executed that is not terminal yet, or finished more than 10 minutes ago, is 409.

Requires authentication using a bearer token — see tokens and scopes.

curl

curl -X POST 'https://neosource.dev/api/jobs/JOB_ID/vm-cache-report' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"key":"string","warm":false,"result":"string"}'

fetch

fetch("https://neosource.dev/api/jobs/JOB_ID/vm-cache-report", {
  method: "POST",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"key":"string","warm":false,"result":"string"}),
});

Path parameters

job_idrequired: string

Request bodyrequired

application/json

VmCacheReportDto

object

A direct-VM job's cache outcome (ADR 0146).

evicted

array

Committed disks evicted for this job, at most 256 (400 above that).

items

VmCacheEvictionDto

object

A committed cache disk a direct-VM agent evicted.

evicted_at: integer | nullint64
When the disk was gone, in epoch milliseconds by the agent's clock. The server ignores the eviction if the disk was committed after it; without it the eviction applies unconditionally.
keyrequired: string
`[A-Za-z0-9_-]{1,64}`, else 400.
repo_idrequired: string

fork_failed

boolean

The run is cold because forking the committed disk failed, not because there was none, so the server keeps the disk `committed`.

keyrequired

string

The cache key the agent derived. The server derives its own; a mismatch is logged, never trusted.

memory_peak_mib

integer | nullint32

The job cgroup's peak memory, in MiB.

resultrequired

VmCacheResult

string

What became of a job's cache disk fork at completion.

"committed""discarded""commit_failed"

warmrequired

boolean

The job forked a committed disk rather than a fresh one.

Responses

204Recorded, already recorded, or dropped (failed the checks)

Standard errors

Bodies documented once for the whole API — see standard errors.

400Bad Request — one of: invalid_input
401Authentication required
403Forbidden — one of: forbidden
404Not Found — one of: not_found
409Conflict — one of: conflict
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget