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)
| Field | Type | Required | Description |
|---|---|---|---|
file | file | Yes | One or more files (repeat for multiple). Any field name works; every part with a filename is saved |
user_id | integer | Yes | User identifier for quota tracking |
service | string | Yes | Service 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
| Code | Description |
|---|---|
202 | Job accepted and queued. The Location header points to /download/{id} |
400 | The multipart body could not be parsed (for example, no boundary or a truncated body) |
413 | The request body exceeds the upload limit (MAX_UPLOAD_SIZE) |
415 | The Content-Type header is missing or not multipart/form-data |
422 | The request parsed, but a field is invalid: user_id missing or not a number, unknown service, or no run.sh uploaded |
500 | The 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
servicemust 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 with422. Its contents are not checked at upload time: an unsafe or broken script results inInvalidstatus when the client tries to execute it dest_idis populated after the job is dispatched to a client
GET /download/
Get job status or download completed results.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | integer | Job 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
| Code | Description |
|---|---|
200 | JSON job status or ZIP file (check Content-Type) |
404 | Job not found |
500 | Server error |
Notes
- The same endpoint returns JSON or ZIP depending on job state. Only
Completedjobs return the ZIP - Terminal states other than
Completed(Failed,Invalid,Killed,Lost,Cleaned) keep returning JSON with200. Use/download_partial/{id}to get the files of a failed job - All files present in the job directory after
run.shfinishes 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
| Parameter | Type | Description |
|---|---|---|
id | integer | Job 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
| Code | Description |
|---|---|
200 | ZIP file with current job state |
400 | Job’s service is not configured on the server |
404 | Job not found, job not dispatched yet (Queued), or the client no longer has the payload |
500 | Server 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_URLby replacing its last path segment withretrieve_partial
POST /terminate/
Cancel a running job.
Parameters
| Parameter | Type | Description |
|---|---|---|
id | integer | Job 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
statusfield in the response reflects the in-memory default and is not meaningful here. QueryGET /download/{id}to confirm the job’s actual status after termination.
Status Codes
| Code | Description |
|---|---|
200 | Job terminated successfully |
404 | Job not found |
500 | Server 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
Queuedjobs cannot be terminated: there is no client payload yet, the client answers404, the server returns500and the job staysQueued(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 thoughoutput.zipis 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
| Code | Description |
|---|---|
200 | Server is healthy |
503 | Database 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.