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

Server API Endpoints

The orchestrator server exposes a REST API for job submission and retrieval.

Base URL

http://localhost:5000

Interactive Documentation

Swagger UI is available at:

http://localhost:5000/swagger

Endpoints

POST /upload

Submit a new job for processing.

Request

  • Content-Type: multipart/form-data
  • Max size: 400MB by default, set with MAX_UPLOAD_SIZE (see Server Configuration)
FieldTypeRequiredDescription
filefileYesOne or more files (repeat for multiple). Any field name works; every part with a filename is saved
user_idintegerYesUser identifier for quota tracking
servicestringYesService name, lowercase (must be configured on server)

Example

curl -X POST http://localhost:5000/upload \
  -F "file=@run.sh" \
  -F "file=@input.pdb" \
  -F "user_id=1" \
  -F "service=example"

Response

HTTP/1.1 202 Accepted
Location: /download/1
{
  "id": 1,
  "status": "Queued",
  "message": "Job successfully uploaded"
}

The job is queued, not finished. Poll the URL in the Location header (GET /download/{id}) to follow it.

Status Codes

CodeDescription
202Job accepted and queued. The Location header points to /download/{id}
400The multipart body could not be parsed (for example, no boundary or a truncated body)
413The request body exceeds the upload limit (MAX_UPLOAD_SIZE)
415The Content-Type header is missing or not multipart/form-data
422The request parsed, but a field is invalid: user_id missing or not a number, unknown service, or no run.sh uploaded
500The server failed to store the job (disk or database error). The request can be retried

Every error response has a JSON body with a message explaining the problem.

Notes

  • The service must match a configured service on the server exactly (service names are lowercase)
  • Files are stored by base name only: directory parts are stripped, and two files with the same name overwrite each other
  • Other text fields are accepted and ignored
  • The entry point script must be named exactly run.sh (hardcoded, case-sensitive). An upload without it is rejected with 422. Its contents are not checked at upload time: an unsafe or broken script results in Invalid status when the client tries to execute it
  • dest_id is populated after the job is dispatched to a client

GET /download/

Get job status or download completed results.

Parameters

ParameterTypeDescription
idintegerJob ID from upload response

Example

# Check status (returns JSON when not completed)
curl http://localhost:5000/download/1

# Download results (returns ZIP when completed)
curl -o results.zip http://localhost:5000/download/1

Response

When the job is not yet completed, returns JSON:

{
  "id": 1,
  "status": "Running",
  "message": ""
}

When the job is completed, returns:

  • Content-Type: application/zip
  • Body: ZIP archive of all output files

Status Codes

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

Notes

  • The same endpoint returns JSON or ZIP depending on job state. Only Completed jobs return the ZIP
  • Terminal states other than Completed (Failed, Invalid, Killed, Lost, Cleaned) keep returning JSON with 200. Use /download_partial/{id} to get the files of a failed job
  • All files present in the job directory after run.sh finishes are included

Usage Pattern

while true; do
  ct=$(curl -s -o response.tmp -w '%{content_type}' http://localhost:5000/download/1)
  if [[ "$ct" == application/zip* ]]; then
    mv response.tmp results.zip
    break
  fi
  status=$(jq -r '.status' response.tmp)
  case "$status" in
    Failed|Invalid|Killed|Lost|Cleaned) echo "Job ended: $status"; break ;;
  esac
  echo "Status: $status"
  sleep 5
done

GET /download_partial/

Retrieve current job state regardless of completion status.

Use this endpoint to debug stuck or incomplete jobs by downloading the current workspace state as a ZIP file.

Parameters

ParameterTypeDescription
idintegerJob ID from upload response

Example

curl -o partial_results.zip http://localhost:5000/download_partial/1

Response

  • Content-Type: application/zip
  • Body: ZIP archive containing current job directory state

Status Codes

CodeDescription
200ZIP file with current job state
400Job’s service is not configured on the server
404Job not found, job not dispatched yet (Queued), or the client no longer has the payload
500Server error, or the client could not build the archive (for example after cleanup)

Notes

  • The ZIP comes from the client’s working directory, not from the server’s copy
  • The client URL is derived from the service’s DOWNLOAD_URL by replacing its last path segment with retrieve_partial

POST /terminate/

Cancel a running job.

Parameters

ParameterTypeDescription
idintegerJob ID to terminate

Example

curl -X POST http://localhost:5000/terminate/1

Response

On success:

{
  "id": 1,
  "status": "Unknown",
  "message": "job terminated"
}

On failure:

{
  "id": 1,
  "status": "Unknown",
  "message": "could not terminate job"
}

The status field in the response reflects the in-memory default and is not meaningful here. Query GET /download/{id} to confirm the job’s actual status after termination.

Status Codes

CodeDescription
200Job terminated successfully
404Job not found
500Server error or termination failed

Notes

  • Termination is not gated on the job’s current status: the server locks the job, forwards the kill to the client regardless of what state it’s in, and rolls the status back to what it was before if the kill fails
  • Terminated jobs will have status Killed
  • The server sends a termination signal to the client, which then kills the process
  • Queued jobs cannot be terminated: there is no client payload yet, the client answers 404, the server returns 500 and the job stays Queued (it will still run later)
  • Terminating a job that already finished reports success and changes its status to Killed. From then on /download/{id} returns JSON instead of the ZIP, even though output.zip is still on the server

GET /health

Health check endpoint.

Example

curl http://localhost:5000/health

Response

On success:

{
  "status": "ok",
  "database": "ok"
}

On failure (database unreachable), the response is a bare 503 with no body.

Status Codes

CodeDescription
200Server is healthy
503Database is unreachable

GET /

Ping endpoint for basic connectivity check.

Example

curl http://localhost:5000/

Response

{"message": "pong"}

GET /swagger

Interactive API documentation.

Example

Open in browser:

http://localhost:5000/swagger

Provides:

  • Interactive API explorer
  • Request/response schemas
  • Try-it-out functionality

Error Responses

Error responses from /upload, /download, /download_partial and /terminate follow this format (/health returns a bare 503 instead):

{
  "id": 0,
  "status": "Unknown",
  "message": "Description of the error"
}

Rate Limiting

The server does not implement rate limiting directly. Use a reverse proxy (nginx, traefik) for rate limiting in production.

Authentication

The server does not implement authentication directly. The user_id field is trusted as provided. Implement authentication at the reverse proxy layer or in your application.

See Also