Skip to main content

Endpoints

The Palmetto API provides endpoints for querying and managing the Slurm scheduler. For full request and response schema details, refer to the Slurm REST API documentation.

Authentication Headers​

All authenticated endpoints require one of:

Authorization: MUNGE <credential>      # from a cluster node
Authorization: Bearer <token>           # issued by RCD

See Authentication for details.

Meta Endpoints​

These endpoints do not require authentication.

MethodPathDescription
GET/meta/versions/supportedJSON array of supported API versions
GET/meta/versions/latestLatest version string (plain text)
GET/pingReturns pong (liveness check)

Slurm Endpoints​

The Palmetto API exposes the Slurm controller endpoints at /slurm/{version}/... and the Slurm accounting database endpoints at /slurmdb/{version}/.... See API Versioning for available versions.

For a complete list of endpoints and their request/response schemas, refer to the Slurm REST API documentation.

List Jobs​

List running jobs from the Slurm controller (requires slurm:read):

curl -H "Authorization: Bearer $PALMETTO_API_KEY" \
  https://api.palmetto.clemson.edu/slurm/latest/jobs | jq '.jobs[] | {job_id, name, job_state}'

Query historical job records from the accounting database (requires slurmdb:read):

curl -H "Authorization: Bearer $PALMETTO_API_KEY" \
  "https://api.palmetto.clemson.edu/slurmdb/latest/jobs?start_time=$(date -d '1 day ago' +%s)" \
  | jq '.jobs[] | {job_id, name, state_current}'

Submit a Job​

Submit a job to your node owner partition (requires slurm:jobs:manage):

curl -X POST https://api.palmetto.clemson.edu/slurm/v0.0.44/job/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PALMETTO_API_KEY" \
  -d '{
    "job": {
      "name": "test-job",
      "partition": "ownerpartition",
      "account": "ownerpartition",
      "environment": [
        "PATH=/usr/local/bin:/usr/bin:/usr/local/sbin:/usr/sbin"
      ],
      "current_working_directory": "/home/p2ownerpartition",
      "tasks": 1,
      "script": "#!/bin/bash\nhostname\nsleep 30\necho done",
      "time_limit": {"set": true, "number": 600}
    }
  }'

Replace ownerpartition with the name of your node owner partition and p2ownerpartition with the service account home directory.

Cancel a Job​

Cancel a running job (requires slurm:jobs:manage):

curl -X DELETE -H "Authorization: Bearer $PALMETTO_API_KEY" \
  https://api.palmetto.clemson.edu/slurm/latest/job/12345

Caching​

GET responses are cached for short periods (2–60 seconds depending on the endpoint). This means rapidly repeated queries may return slightly stale data.

Responses include standard HTTP caching headers (Cache-Control, Date, Expires, Age) so your client can assess data freshness.

You can opt into stale cached data when the upstream Slurm service is unavailable by sending the stale-if-error directive:

Cache-Control: stale-if-error=300

This returns the last cached response (up to 300 seconds past expiry) instead of a 500 error when Slurm is unreachable. Without this header, upstream failures are passed through as errors.

Rate Limiting​

The API applies per-IP rate limiting using a token bucket algorithm. If you exceed the limit, requests will return 429 Too Many Requests. Implement exponential backoff in your client code.