Client API Endpoints
The client exposes endpoints for the orchestrator server to submit jobs and retrieve results.
Note: These endpoints are typically only accessed by the orchestrator server, not by end users.
Base URL
http://localhost:9000
Endpoints
POST /submit
Receive a job payload from the orchestrator server.
Request
- Content-Type:
multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | One or more job files. Any field name works; parts without a filename are ignored |
Example
curl -X POST http://localhost:9000/submit \
-F "file=@run.sh" \
-F "file=@input.pdb"
Response
{
"id": 1,
"status": "Prepared",
"loc": "/opt/data/1",
"pid": 0,
"killed": false
}
Status Codes
| Code | Description |
|---|---|
200 | Payload received successfully |
400 | Malformed multipart request |
500 | Server error |
Notes
- The client stores files (by base name) in
DATA_PATH/<id>and creates a payload record - The whole request is held in memory while it is processed, and there is no body size limit on the client
- Status starts as
Prepared, waiting for the Runner task - The
idis returned to the server and stored asdest_id
GET /retrieve_partial/
Retrieve current payload state regardless of completion status.
Use this endpoint to debug stuck or incomplete payloads by downloading the current workspace state as a ZIP file. This endpoint is typically called by the orchestrator server, not end users.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | integer | Payload ID from submit response |
Example
# Download partial results for debugging
curl -o partial_results.zip http://localhost:9000/retrieve_partial/1
Response
- Content-Type:
application/zip - Body: ZIP archive containing current payload directory state
Status Codes
| Code | Description |
|---|---|
200 | ZIP file with current payload state |
404 | Payload not found |
500 | Server error |
Notes
- The
/retrieve_partialendpoint on the client is used internally by the server’s/download_partialendpoint - Path traversal protection is applied to all ZIP operations
GET /retrieve/
Retrieve results of a completed payload.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | integer | Payload ID from submit response |
Example
curl -o results.zip http://localhost:9000/retrieve/1
Response
When the payload is not yet completed, returns a JSON body:
{
"id": 1,
"status": "Running",
"loc": "/opt/data/1",
"pid": 12345,
"killed": false
}
When the payload is completed, returns:
- Content-Type:
application/zip - Body: ZIP archive of all files in the payload directory
Status Codes
| Code | Description |
|---|---|
200 | JSON payload status or ZIP file (check Content-Type) |
404 | Payload not found |
500 | Server error |
Notes
- The ZIP includes all files in the working directory after
run.shexecution, including.orchestrator.exit - Original input files are included unless deleted by
run.sh - The archive is written to
output.zipin the payload directory on the first request and reused afterwards
POST /kill/
Terminate a running payload.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | integer | Payload ID to terminate |
Example
curl -X POST http://localhost:9000/kill/1
Response
On success (200 OK):
- Empty body
On failure:
404if payload not found (with an empty payload JSON body)500if kill operation failed
Status Codes
| Code | Description |
|---|---|
200 | Payload terminated successfully |
404 | Payload not found |
500 | Kill operation failed |
Notes
- Sends SIGTERM to the process PID stored for the payload; silently succeeds if no PID is set yet or the process is already gone
- Sets the payload’s
killedflag. The Updater changes the status toKilledonly if the payload isRunning; a payload that already finished keeps its status - This endpoint is called by the server’s
/terminate/{id}endpoint
GET /load
Report current CPU usage.
Example
curl http://localhost:9000/load
Response
45.2
Returns a float representing CPU usage percentage (0-100). The value is sampled when the request arrives, so each call takes a fraction of a second.
Use Cases
- Load-aware job distribution (planned feature)
- Monitoring client health
- Capacity planning
GET /health
Health check endpoint.
Example
curl http://localhost:9000/health
Response
{
"status": "ok",
"database": "ok"
}
GET /
Ping endpoint for basic connectivity check.
Example
curl http://localhost:9000/
Response
{"message": "pong"}
Payload States
Payloads on the client go through these states:
| State | Description |
|---|---|
Prepared | Received from server, waiting for execution |
Running | Currently executing run.sh |
Completed | Execution finished successfully |
Failed | Execution failed (non-zero exit code, or the process could not be started) |
Invalid | run.sh missing, unsafe, or failed validation |
Killed | Terminated via /kill/{id} |
Lost | Process disappeared without writing .orchestrator.exit |
Cleaned | Payload directory removed by the cleaner task |
Security Considerations
The client API should never be exposed to the public internet:
- No authentication is implemented
- Arbitrary code execution via
run.sh - Internal service communication only
Recommendations:
- Use internal networks / VPCs
- Firewall rules: allow only orchestrator server IP
- Docker networks with no external exposure