Documentation

Overview

RobinGrid exposes a small, stable API surface for finding available GPU nodes and dispatching containerized jobs against them. There are two ways to talk to it:

• @robingrid/sdk: a typed Node.js/TypeScript client, published on npm.
• REST API: plain HTTP + JSON under /api/v1, usable from curl or any language.

Both talk to the same endpoints, so the reference below applies whichever you use. The SDK is just a thin, typed wrapper around the REST calls.

Installation

Install the SDK from npm:

npm install @robingrid/sdk

Requires Node.js 18+ (uses the global fetch, no extra HTTP dependency). Package page: npmjs.com/package/@robingrid/sdk.

Authentication

Every request (SDK or REST) is authenticated with an API key passed as a bearer token. Generate one from the Console's API Configuration tab.

Authorization: Bearer rg_live_...

Requests with a missing or invalid key receive a 401 with an { "error": "Invalid or missing API key" } body.

Quickstart

Find the cheapest matching node, dispatch a job to it, then poll for its status:

import { RobinGrid } from "@robingrid/sdk";

const client = new RobinGrid({ apiKey: "rg_live_..." });

const node = await client.nodes.findCheapest({
  gpu: "RTX 4090",
  region: "US-East",
});

const job = await client.jobs.create({
  nodeId: node.id,
  containerImage: "runpod/stable-diffusion-v1-5",
  envVars: { PROMPT: "a robin flying over a server farm" },
});

console.log(job.id, job.status); // "job_abc123" "PENDING_BID"

// Poll until it finishes
const finished = await client.jobs.get(job.id);
console.log(finished.status, finished.logs);

SDK Reference

const client = new RobinGrid({
  apiKey: "rg_live_...",
  baseUrl: "http://localhost:3000/api/v1", // optional
});

const nodes = await client.nodes.search({ gpu: "H100", maxPingMs: 20 });

const node = await client.nodes.findCheapest({ gpu: "RTX 4090" });

const job = await client.jobs.create({
  containerImage: "ollama/ollama:latest",
  envVars: { MODEL: "llama3" },
  gpuModelPreference: "H100",
});

const job = await client.jobs.get("job_abc123");

REST API

Base URL: https://api.robingrid.xyz/api/v1. Every endpoint requires the Authorization: Bearer header shown above.

curl -X POST https://api.robingrid.xyz/api/v1/jobs \
  -H "Authorization: Bearer rg_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "containerImage": "ollama/ollama:latest",
    "envVars": { "MODEL": "llama3" },
    "gpuModelPreference": "H100"
  }'

curl https://api.robingrid.xyz/api/v1/jobs/job_abc123 \
  -H "Authorization: Bearer rg_live_..."

curl "https://api.robingrid.xyz/api/v1/nodes?gpu=4090&maxPingMs=30" \
  -H "Authorization: Bearer rg_live_..."

Job Lifecycle

A job moves through the following statuses. Poll jobs.get() until it reaches a terminal state.

Errors

Errors are returned as JSON with an error message and a non-2xx status code. The SDK wraps these in a RobinGridApiError with a status property.

try {
  await client.jobs.get("does_not_exist");
} catch (err) {
  if (err instanceof RobinGridApiError) {
    console.log(err.status, err.message); // 404 "Job not found"
  }
}