Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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
FieldTypeRequiredDescription
filefileYesOne 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

CodeDescription
200Payload received successfully
400Malformed multipart request
500Server 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 id is returned to the server and stored as dest_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

ParameterTypeDescription
idintegerPayload 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

CodeDescription
200ZIP file with current payload state
404Payload not found
500Server error

Notes

  • The /retrieve_partial endpoint on the client is used internally by the server’s /download_partial endpoint
  • Path traversal protection is applied to all ZIP operations

GET /retrieve/

Retrieve results of a completed payload.

Parameters

ParameterTypeDescription
idintegerPayload 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

CodeDescription
200JSON payload status or ZIP file (check Content-Type)
404Payload not found
500Server error

Notes

  • The ZIP includes all files in the working directory after run.sh execution, including .orchestrator.exit
  • Original input files are included unless deleted by run.sh
  • The archive is written to output.zip in the payload directory on the first request and reused afterwards

POST /kill/

Terminate a running payload.

Parameters

ParameterTypeDescription
idintegerPayload ID to terminate

Example

curl -X POST http://localhost:9000/kill/1

Response

On success (200 OK):

  • Empty body

On failure:

  • 404 if payload not found (with an empty payload JSON body)
  • 500 if kill operation failed

Status Codes

CodeDescription
200Payload terminated successfully
404Payload not found
500Kill 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 killed flag. The Updater changes the status to Killed only if the payload is Running; 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:

StateDescription
PreparedReceived from server, waiting for execution
RunningCurrently executing run.sh
CompletedExecution finished successfully
FailedExecution failed (non-zero exit code, or the process could not be started)
Invalidrun.sh missing, unsafe, or failed validation
KilledTerminated via /kill/{id}
LostProcess disappeared without writing .orchestrator.exit
CleanedPayload 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

See Also