canonical: https://jentic.com/apis/salad.cloud/salad

# Salad SaladCloud API

The SaladCloud API deploys and runs container groups on SaladCloud's distributed GPU and CPU network, organised by organization and project. It creates, updates, starts, stops, and deletes container groups, and lets you inspect, restart, recreate, or reallocate individual instances. Job queues and inference endpoints accept asynchronous jobs with an input payload and optional webhook, while GPU class listings, CPU and GPU availability checks, quotas, and log-entry queries support capacity planning and debugging.

## For AI agents

Deploy and scale GPU container groups, submit jobs to queues or inference endpoints, and check GPU availability on SaladCloud.

## Scope

Does not build container images, host model registries, or bill usage through the API. Use for running and managing container groups, queues, and inference jobs on SaladCloud only.

## Capabilities

- Create a container group with an image, replica count, restart policy, and autostart policy, then start or stop it
- Restart, recreate, or reallocate a single container group instance that is misbehaving
- Submit jobs with an input payload and optional webhook to a project queue, then fetch or cancel them
- Send jobs to a SaladCloud inference endpoint and poll the job for its result
- Check CPU and GPU availability for requested GPU classes and country codes before deploying
- Query log entries across an organization for a time range, and read a container group's system logs
- List GPU classes and read organization quotas to plan capacity

## Use cases

### AI agent GPU workload operator

An AI agent asked to bring a model server online needs to create and manage GPU workloads without the developer writing a SaladCloud client. Through Jentic the agent searches for 'deploy a container group', loads create_container_group with its input schema, and supplies the required name, container, replicas, restart_policy, and autostart_policy fields while the Salad-Api-Key header is injected at call time. It can then start the group and list instances to confirm they are running.

Example prompt: Create a container group in project ml-prod with 3 replicas of an inference image, start it, then list its instances to confirm they are running

### Queue-based batch inference

Batch workloads like transcription or image generation fit a job-queue pattern rather than direct HTTP calls. SaladCloud queues accept jobs whose required input field carries the payload, with optional metadata and a webhook for completion. Container groups connected to the queue pull work, and the job can be fetched by queue_job_id or deleted if no longer needed.

Example prompt: POST a job with an input payload and a webhook URL to the queue named transcribe, then poll the job by its id until it completes

### Capacity check before scaling

Distributed GPU supply varies by class and location, so deploys should check capacity first. The sce-gpu-availability operation takes required gpu_classes plus optional country_codes, CPU, memory, and storage, and the GPU class list and quotas show what the organization can request. This lets an operator pick a class and region that can actually be filled.

Example prompt: List GPU classes, then call the GPU availability check for two classes in country code US and report which has capacity

### Instance troubleshooting

When one node in a group misbehaves, replacing it beats restarting the whole deployment. SaladCloud exposes restart, recreate, and reallocate actions on a single container_group_instance_id, and system logs plus organization-wide log-entry queries over a start_time and end_time help find the cause first.

Example prompt: Query log entries for the last hour with a query filter for errors, then reallocate the instance that produced them

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/organizations/{organization_name}/projects/{project_name}/containers` | Create a container group |
| POST | `/organizations/{organization_name}/projects/{project_name}/containers/{container_group_name}/start` | Start a container group |
| GET | `/organizations/{organization_name}/projects/{project_name}/containers/{container_group_name}/instances` | List container group instances |
| POST | `/organizations/{organization_name}/projects/{project_name}/containers/{container_group_name}/instances/{container_group_instance_id}/reallocate` | Reallocate an instance |
| POST | `/organizations/{organization_name}/projects/{project_name}/queues/{queue_name}/jobs` | Create a queue job |
| POST | `/organizations/{organization_name}/inference-endpoints/{inference_endpoint_name}/jobs` | Create an inference endpoint job |
| POST | `/organizations/{organization_name}/availability/sce-gpu-availability` | Get GPU availability |
| GET | `/organizations/{organization_name}/gpu-classes` | List GPU classes |

## Key resources

- **Container groups** — Create, update, start, stop, delete, and read system logs for GPU or CPU container deployments
- **Container group instances** — List, inspect, update, restart, recreate, and reallocate individual instances
- **Queues and jobs** — Create queues and submit, fetch, list, or delete jobs
- **Inference endpoints** — List endpoints and create, fetch, or cancel inference jobs
- **Organization data** — GPU classes, quotas, CPU and GPU availability, log entries, and the webhook secret key

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 72 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 57 / 100
  - Developer Experience & Jentic Compatibility: 70 / 100
  - AI-Readiness & Agent Experience: 97 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 65 / 100
- **View full report:** https://jentic.com/apis/salad.cloud/salad/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring SaladCloud by hand means sending the Salad-Api-Key header, building long organization and project paths for every call, and polling queue and inference jobs for completion. Through Jentic you install once, import SaladCloud from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** SaladCloud puts organization_name, project_name, and container_group_name in the URL path, so a rule can pin your agent to one project or one container group and the operations you pick. You choose the operations it may call, so destructive ones like deleting a container group or rotating the webhook secret key are not included unless you add them.
- **Credential handling:** Your SaladCloud API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'deploy a container group' or 'check GPU availability', and Jentic returns the matching SaladCloud operation with its input schema so the agent fills the right path and body fields.

## Related APIs

- **Lambda Cloud** — On-demand GPU instances from a data-centre provider
- **Replicate** — Run hosted machine learning models through an API
- **Baseten** — Model deployment and serving platform
- **Hugging Face** — Model hub to source the weights your containers serve

## FAQ

### What authentication does the SaladCloud API use?

Per its OpenAPI spec, the SaladCloud API authenticates with an API key sent in the `Salad-Api-Key` request header, applied to every operation. Through Jentic the key is held by your own instance and added at call time, so the agent never handles it.

### Can I check GPU availability before deploying with the SaladCloud API?

Yes. POST `/organizations/{organization_name}/availability/sce-gpu-availability` takes a required gpu_classes list plus optional country_codes, cpu, memory, and storage_amount, and returns availability for that request. GET `/organizations/{organization_name}/gpu-classes` lists the classes you can ask for.

### What are the rate limits for the SaladCloud API?

The OpenAPI spec does not specify rate limits. Check the SaladCloud documentation at https://docs.salad.com/api-reference for current limits, and use the quotas operation to see your organization's resource quotas.

### Is there a SaladCloud MCP server?

You don't need an MCP server to give your agent SaladCloud. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the deployment and job operations it needs, found by intent rather than preloaded into its context.

### How do I submit a job to a SaladCloud queue through Jentic?

Search Jentic for 'submit a job to a queue', load create_queue_job, and execute POST `/organizations/{organization_name}/projects/{project_name}/queues/{queue_name}/jobs` with the required input field and an optional webhook. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can I limit what my agent is allowed to do with the SaladCloud API?

Yes. A rule can allow only the start, stop, and instance-restart operations under `/organizations/acme/projects/ml-prod`/, so the agent can cycle that project's workloads but cannot create new groups, delete queues, or touch another project. Every call it makes is logged.
