REST API

The Rescale REST API is a programmatic interface to the platform. It covers job submission, file and storage management, workspace administration and billing, so another system can drive Rescale without anyone opening a browser. Every endpoint, with its parameters, request and response shapes and worked examples, is in the Rescale API documentation.

What you can use it for

The API exists for integrations rather than for interactive work. The common cases:

• Cloud-bursting from an on-premises scheduler into any cloud provider Rescale supports.
• Managing simulation input and output files, including the archival flow.
• Launching and connecting to interactive sessions as well as batch jobs.
• Driving the vendor application integrations that run jobs in the cloud.
• Automating user on-boarding from your own identity or user-management system.
• Keeping project budgets in step with your system of record.

File transfer through the API is capped at 5 GB per file. Above that, use the Transfer Manager, which is built for datasets the API cannot carry.

Four conventions every request follows

These are the ones that cost people an afternoon, because each fails in a way that looks like something else.

Convention	What goes wrong without it
Use your own platform's host, not the US one by default	A valid key against the wrong host reads as an authentication failure. See regional platforms for the host per platform
Keep the trailing slash: /api/v2/jobs/, never /api/v2/jobs	You get a 301 redirect instead of the resource, and a client that does not follow redirects on a POST silently drops the body
Include the version identifier right after /api/: /api/v2/jobs/	A path with no version falls back to v1, which can be deprecated without notice
Send the key as Authorization: Token <your-key>	Anything else returns 401, including the Bearer form most other APIs use

Versioning

Build against v2, which is what the API documentation covers.

Additive changes such as new fields arrive inside a version, so a client should ignore keys it does not recognize rather than failing on them.

Pagination

Every endpoint that returns a list is paginated, and wraps its results:

{
  "count": 123,
  "previous": null,
  "results": [],
  "next": "https://platform.rescale.com/api/v2/jobs/?page_size=2&page=5"
}

Control it with page and page_size, where page starts at 1. Follow next until it is null to walk the whole set.

Prefer a server-side filter over paging through everything. Those appear as query strings, for example GET /api/v2/jobs/?state=not_completed.

IDs in URLs are opaque short strings such as RcAFeb. You get one from the response of the resource you just created rather than constructing it.

Errors

An error returns the HTTP status code with a JSON body describing the failure:

{
  "detail": "Authentication credentials were not provided."
}

The status codes carry more meaning than the body does, and two of them are easy to misread:

Status	What it means
401 Unauthorized	The key is missing, malformed or expired. API key is no longer active means it expired; User inactive or deleted means the owning user was deactivated
403 Forbidden	The key is valid, but the user it belongs to lacks permission for that resource
404 Not Found	Covers both a nonexistent ID and a resource in a workspace the user cannot see, so it does not distinguish "wrong id" from "no access"
400 Bad Request	Validation failed on a create or update. The body carries per-field messages
5xx	Server side. Retry with backoff

Getting a key

Create one under Preferences > API. What a key can do, how long it lasts under an organization lifetime policy, how to rotate it, and the short-lived key every job gets in RESCALE_API_KEY are all on API keys.

Related

• Developer overview — choosing between the API, the CLI and the MCP Server, and a worked first call
• Rescale API documentation — every published operation, on a separate site
• API keys — creating a key, its scope and its lifetime
• CLI — the same operations as ergonomic shell commands
• MCP Server — the same platform exposed to an AI client
• Transfer Manager — for files above the API's 5 GB limit