MVP job-control and resource-listing endpoints

[tpatki]

Discuss MVP job-control and resource-listing endpoints (submit, list, status, state, cancel, output, nodes).

Note: Generated with assistance from Claude, leveraging some ideas from the existing flux-restful-apis repo by @vsoch. May contain some mistakes that we can fix.

Problem

flux-rest-server currently has no job-control surface (only /api/v1/ and
/api/v1/health). This issue proposes a minimal set of endpoints covering the
job lifecycle — submit, list, inspect, poll, cancel, output — plus a
cluster resource-listing endpoint, each backed by a real, existing Flux
Python API call.

Proposed endpoints

Method	Path	Purpose	Backing Flux API
POST	/api/v1/jobs/submit	Submit a job	flux.job.submit() (jobspec via JobspecV1.from_command())
GET	/api/v1/jobs/list	List jobs	flux.job.list.JobList()
GET	/api/v1/jobs/<id>	Full job info	flux.job.list.job_list_id()
GET	/api/v1/jobs/<id>/state	Cheap state-only poll	job_list_id(attrs=["state","result"])
POST	/api/v1/jobs/<id>/cancel	Cancel a job	flux.job.cancel()
GET	/api/v1/jobs/<id>/output	Get stdout/stderr	flux.job.output.job_output()
GET	/api/v1/nodes/list	List cluster nodes/resources	flux.resource.list.resource_list() → SchedResourceList

Notes:

• /state has no flux-restful-api equivalent — added to give guest callers a
  cheap poll target. Jobs must be submitted with the waitable flag to be
  usable with flux.job.wait(), and only the instance owner may submit jobs
  with that flag — so guest callers can't rely on blocking waits and need to
  poll instead.
• Cancel uses POST .../cancel, matching flux-restful-api's convention within
  the same Flux ecosystem. (SLURM's slurmrestd instead cancels via
  DELETE job/{job_id}, optionally with a signal param — noted here in case
  that precedent is worth revisiting later, e.g. for signal delivery.)
• /output is a separate endpoint (not folded into status) so routine polling
  doesn't have to drag along potentially large output data.
• /nodes mirrors flux-restful-api's GET /v1/nodes. Backed by
  resource_list(), an async call whose future resolves (via .get()) to a
  SchedResourceList with .up/.free/.down/.allocated resource sets
  (the same data flux resource list displays) — useful for clients that
  want capacity info before submitting.

References

• Job submission & monitoring: https://flux-framework.readthedocs.io/projects/flux-core/en/latest/python/job_submission.html
• flux.job.Jobspec (from_command signature): https://flux-framework.readthedocs.io/projects/flux-core/en/latest/python/autogenerated/flux.job.Jobspec.html
• flux.job.list (JobList, job_list_id): https://flux-framework.readthedocs.io/projects/flux-core/en/latest/python/autogenerated/flux.job.list.html
• flux.job.kill (cancel, kill): https://flux-framework.readthedocs.io/projects/flux-core/en/latest/python/autogenerated/flux.job.kill.html
• flux.job.output (job_output, output_watch*): https://flux-framework.readthedocs.io/projects/flux-core/en/latest/python/autogenerated/flux.job.output.html
• flux.resource.list (resource_list, SchedResourceList): https://flux-framework.readthedocs.io/projects/flux-core/en/stable/python/autogenerated/flux.resource.list.html

[tpatki]

In our discussion (@trws @garlick @grondo @bvanessen @tgmachina) on 7/20/2026, we agreed to limit the scope for the minimum viable to the following. Summarized by Claude.

Update: trimming scope

Method	Path	Purpose	Backing Flux API	Response
POST	/api/v1/jobs/submit	Submit a job (basic)	flux.job.submit() (jobspec via JobspecV1.from_command())	201 {"id": <jobid>}
POST	/api/v1/jobs/submit-cli	Submit a job (command-line)	flux.job.submit() (jobspec via JobspecV1.from_submit())	201 {"id": <jobid>}
GET	/api/v1/jobs/<id>/state	Cheap state-only poll	flux.job.list.job_list_id(attrs=["state","result"]).get_jobinfo()	200 {"id": <jobid>, "state": "RUN"} (result added once state == "INACTIVE")
GET	/api/v1/jobs/<id>/events	Stream the job event log	flux.job.event_watch() / flux.job.event_watch_async()	Not a JSON body — 200, then a chunked/SSE stream, one eventlog entry per message

Notes:

• Basic submit takes a structured JSON body (command, num_nodes, cores_per_task, etc.), as already spec'd above.
• Command-line submit accepts the equivalent of flux submit CLI flags directly, backed by JobspecV1.from_submit(). This wraps from_command() + apply_options() and is documented as producing a jobspec "equivalent to what flux submit... would produce," so we get CLI-flag parity (time_limit, dependency, env, shell_options, etc.).
• Streaming events — flux.job.event_watch(flux_handle, jobid) is a generator that synchronously yields each eventlog event as it's posted, with an async counterpart flux.job.event_watch_async() for callback-based consumption. For the REST layer, this maps naturally onto a chunked or SSE response, emitting one event per line.