REST API

HTTP API for jobs, models, hosts, wallets, and API keys. Base URL: https://metalcloud.space/api/v1.

Authentication

Send an API key as a bearer token. Keys start with mc_ and are created in the API keys dashboard. The full key is returned once, on create.

Authorization: Bearer mc_your_key

Job routes also accept the same key in X-API-Key. Login returns a JWT you can send the same way. A missing or unknown token returns 401.

{
  "success": false,
  "message": "Invalid or expired token"
}

Jobs

/api/v1/jobs is the customer job API. Create a job with the Python client or with JSON.

from metalcloud import Client

client = Client(api_key="mc_...")
job = client.jobs.submit(
    type="inference",
    model_id="mlx-community/Llama-3.2-1B",
    input={"prompt": "Explain unified memory in one sentence."},
    priority="normal",
    min_memory_gb=16,
)
result = job.wait()

model_id must be a repo installed on a host you can reach. See the model library. The example id is the shape hosts report. It is not a promise that every Mac has that model cached.

Create body

Send X-Idempotency-Key (16 to 64 characters) to make a retry return the job created in the last 24 hours instead of a second job. For inference and batch, a max_tokens value equal to the model context length is dropped, and any larger value is cut to the job duration at 25 tokens per second.

A successful create returns success: true and data.job with uuid, type, priority, and status (assigned when a host is free, otherwise queued), plus data.estimate. Status values are pending, queued, assigned, running, completed, failed, cancelled, and timeout.

You can have 10 jobs in pending, queued, assigned, or running at once. Limits per hour: 60 submits, 300 lists, 2,400 status reads, 30 cancels. No matching host returns 503. A balance below the maximum estimate returns 402 with required and available.

Models

These routes need a bearer token. hosts is a comma-separated list of host UUIDs, 50 maximum. Details are in the model library.

Hosts

GET /hosts lists machines with a heartbeat in the last two minutes. GET /hosts/{uuid} returns one active host, including chip_model, memory_gb, gpu_cores, and hourly_rate_gbp. POST /hosts registers a machine and needs a bearer token. Required fields: name, chip_model, memory_gb, gpu_cores, cpu_cores, hourly_rate_gbp.

Wallet and account

Add funds in the billing dashboard. Rates are on the billing page.

API keys

Host dashboard

These routes need a host or admin account.

Machine setup for hosts is in host setup.