GridShare Docs — API Reference, Python SDK, CLI Quickstart

GridShare API Docs

REST API + Python SDK + CLI. Base URL: https://gridshare.in · All endpoints return JSON · TLS only

⚡ Quickstart — 60 seconds

Create an account & top up

Get your API key

Dashboard → API Keys → Create key. Keys start with gs_live_ and never expire unless revoked.

Launch a GPU instance

cURL

Python

CLI

curl -X POST https://gridshare.in/v1/instances \
  -H "Authorization: Bearer gs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "gpu_tier": "Ultra",
    "template": "pytorch",
    "instance_type": "on-demand"
  }'

# Response: {"id":"inst_xxx","status":"starting","ssh_host":"...","ssh_port":22}

import gridshare_sdk as gs

client = gs.Client(api_key="gs_live_YOUR_KEY")

instance = client.instances.create(
    gpu_tier="Ultra",     # RTX 4090
    template="pytorch",  # PyTorch 2.3 + CUDA 12
    instance_type="on-demand"
)
print(instance.ssh_host, instance.ssh_port)  # SSH in

pip install gridshare-cli
gridshare login              # paste your API key
gridshare instances launch \
  --gpu Ultra \
  --template pytorch \
  --type on-demand

# Instance ready in ~30s. SSH auto-configured.
gridshare ssh inst_xxx        # SSH directly

Stop when done — billing stops immediately

curl -X DELETE https://gridshare.in/v1/instances/inst_xxx \
  -H "Authorization: Bearer gs_live_YOUR_KEY"
# Billing stops within seconds of container termination

🔑 Authentication

All API endpoints require a bearer token. Pass your API key in the Authorization header:

Authorization: Bearer gs_live_your_api_key_here

API keys are created at /app → API Keys. You can have up to 10 active keys. Keys are shown only once at creation — store them securely. Revoke anytime.

Rate limits

Endpoint	Limit	Window
/v1/instances	60 req	per minute
/v1/serverless/*/run	300 req	per minute
/buyers/signup	10 req	per minute
All other	200 req	per minute

Exceeded limits return 429 Too Many Requests with a Retry-After header.

🐍 Python SDK

Official Python client. Wraps the REST API with typed responses, retries, and async support.

pip install gridshare-sdk

import gridshare_sdk as gs

# Initialize (or set GS_API_KEY env var)
client = gs.Client(api_key="gs_live_...")

# — Instances —
instance = client.instances.create(gpu_tier="Ultra", template="pytorch")
instances = client.instances.list()
client.instances.stop("inst_xxx")

# — Serverless —
result = client.serverless.run(
    endpoint="my-llama-3-8b",
    input={"prompt": "Hello in Hindi"}
)

# — SSH Keys —
client.ssh_keys.add(label="MacBook", public_key="ssh-ed25519 AAAA...")

# — Secrets —
client.secrets.create(name="HF_TOKEN", value="hf_abc123...")

# — Async variant —
import asyncio
async def main():
    async with gs.AsyncClient(api_key="gs_live_...") as c:
        inst = await c.instances.create(gpu_tier="Pro", template="jupyter")
asyncio.run(main())

Set GS_API_KEY environment variable to avoid passing the key in code. The SDK reads it automatically.

💻 CLI Reference

pip install gridshare-cli
gridshare --version   # gridshare-cli 1.0.0

# Auth
gridshare login                           # paste API key
gridshare logout

# Instances
gridshare instances list
gridshare instances launch --gpu Ultra --template pytorch
gridshare instances launch --gpu Pro --template jupyter
gridshare instances stop <id>
gridshare instances logs <id>             # stream container stdout
gridshare ssh <id>                         # SSH directly (key auto-configured)
gridshare jupyter <id>                     # open JupyterLab in browser

# SSH Keys
gridshare ssh-keys list
gridshare ssh-keys add --label "MacBook" --file ~/.ssh/id_ed25519.pub
gridshare ssh-keys delete <id>

# Secrets (encrypted env vars)
gridshare secrets list
gridshare secrets set HF_TOKEN hf_abc123...
gridshare secrets delete HF_TOKEN

# Wallet
gridshare wallet balance
gridshare wallet topup                    # opens UPI payment in browser

# Serverless
gridshare serverless list
gridshare serverless deploy --name my-model --image myrepo/model:latest
gridshare serverless run my-model '{"prompt":"hello"}'

⚡ Instances API

Create, list, stop GPU instances. Billing starts at boot, stops at termination.

POST/v1/instances

Launch a new GPU instance.

# Request body
{
  "gpu_tier": "Ultra",          # Starter|Plus|Standard|Pro|ProMax|Ultra|Extreme
  "template": "pytorch",      # pytorch|tensorflow|jupyter|vllm|sd|comfyui|ollama|custom
  "instance_type": "on-demand", # on-demand
  "docker_image": "",          # optional: custom image (overrides template)
  "env": {"MY_VAR": "value"},  # optional: additional env vars
  "use_secrets": true,         # inject saved secrets at /run/gs_secrets/env
  "ports": [8888, 7860],       # optional: TCP ports to expose
  "gpu_count": 1                # 1 or 2 GPUs (where available)
}

GET/v1/instances

List all running instances for your account.

GET/v1/instances/{id}

Get instance status, SSH details, GPU metrics, and billing info.

DELETE/v1/instances/{id}

Stop and terminate an instance. Billing stops within seconds.

# Response example
{
  "id": "inst_k9x2m",
  "status": "running",  # starting|running|stopped|failed
  "gpu": "RTX 4090",
  "gpu_vram_gb": 24,
  "template": "pytorch",
  "ssh_host": "45.12.xxx.xxx",
  "ssh_port": 22,
  "jupyter_url": "https://gridshare.in/jupyter/inst_k9x2m",
  "started_at": "2026-06-03T10:30:00Z",
  "cost_inr": 2.25,          # total so far
  "city": "Bangalore"
}

Available templates & custom Docker

Template ID	What you get	Use case
pytorch	PyTorch 2.3, CUDA 12.1, cuDNN 8.9	Training, fine-tuning, research
tensorflow	TF 2.16, CUDA 12, cuDNN	TF/Keras workloads
jupyter	JupyterLab 4, PyTorch, numpy, pandas — auto-starts on port 8888	Interactive notebooks
vllm	vLLM pre-installed — SSH in & run `gridshare-serve <model>` (you pick the model)	LLM serving, Llama 3/Mistral
ollama	Ollama + Llama 3 8B pre-pulled	Local LLM, quick prototypes
sd	Stable Diffusion WebUI (Auto1111) — auto-starts on port 7860	Image generation
comfyui	ComfyUI + SDXL + FLUX nodes — auto-starts on port 8188	Advanced image workflows
whisper	FasterWhisper Large v3, REST API	Speech-to-text, transcription
deepseek	DeepSeek-Coder v2, vLLM server	Code generation
ubuntu	Bare Ubuntu 22.04 + CUDA drivers	Custom setup from scratch
custom	Your Docker image from any registry	Any framework, any model

🔐 SSH Keys

Upload your SSH public keys once. They're automatically added to ~/.ssh/authorized_keys on every instance you launch — no manual key copy needed.

POST/buyers/ssh-keys/

Add an SSH public key to your account. Max 10 keys.

{"label": "MacBook Pro", "public_key": "ssh-ed25519 AAAA..."}

GET/buyers/ssh-keys/

List all SSH keys on your account (public keys returned, not private).

DELETE/buyers/ssh-keys/{id}

Remove an SSH key. Does not affect running instances.

💡 Pro tip: Add your key once, then every gridshare ssh inst_xxx command works without any key flags.

🔑 Key-based auth is the default. When at least one SSH key is registered on your account, new instances are provisioned with password authentication disabled — you log in with your key only. If no key is registered, instances fall back to a generated password (shown in the dashboard). We recommend adding a key: it's both more secure and faster to connect.

🔒 Secrets (Encrypted Env Vars)

Store sensitive values (HuggingFace tokens, API keys, database URLs) encrypted at rest. Inject them into instance containers without hardcoding in requests.

POST/buyers/secrets/

Create a secret. Value is encrypted before storage.

{"name": "HF_TOKEN", "value": "hf_aBcDe12345..."}
# Name must be valid env var (A-Z, 0-9, underscore)

GET/buyers/secrets/

List secrets by name (values never returned after creation).

DELETE/buyers/secrets/{id}

Delete a secret.

Enable secret injection when launching:

# With CLI
gridshare instances launch --gpu Ultra --template pytorch --use-secrets

# With API
{"gpu_tier": "Ultra", "template": "pytorch", "use_secrets": true}

Where secrets appear inside the instance

Injected secrets are written to a file at /run/gs_secrets/env inside the container — they are not set as environment variables. The file contains plain KEY=VALUE lines:

# Shell — load all secrets into the current session
source /run/gs_secrets/env

# Python — parse the file directly
secrets = dict(
    line.split("=", 1)
    for line in open("/run/gs_secrets/env").read().splitlines()
    if line and not line.startswith("#")
)
hf_token = secrets["HF_TOKEN"]

The legacy behaviour (secrets as container environment variables) is still available by launching with GRIDSHARE_LEGACY_ENV_SECRETS=1 in env, but it is discouraged: environment variables are visible to the host machine's owner via docker inspect, while the secrets file is mounted only inside the container.

⚠️ Secret values are shown once at creation. Store them separately. Decryption only happens at instance launch time, never returned via API.

⚠️ Honest security note: GridShare instances run on hardware owned by independent providers. File-based injection protects against casual inspection, but a determined host owner with root access can read container memory. Never inject production credentials into Community-tier instances — use scoped, revocable tokens (e.g. a read-only HuggingFace token) and rotate them after sensitive workloads.

🔮 Serverless API

Deploy models as HTTP endpoints. Scale to zero when idle. Billed per 100ms of active compute (₹0.0125/sec for RTX 4090 tier).

POST/v1/serverless/

Create a serverless endpoint.

{
  "name": "my-llama-3-8b",
  "docker_image": "ghcr.io/myorg/llama3-vllm:latest",
  "gpu_tier": "Ultra",
  "min_workers": 0,      # 0 = scale to zero
  "max_workers": 5,
  "use_secrets": true  # inject saved secrets at /run/gs_secrets/env
}

POST/v1/serverless/{name}/run

Invoke the endpoint. Blocks until result is ready (or use async variant).

{"prompt": "Explain transformers in Hindi", "max_tokens": 512}
# Response: {"output": "...", "compute_ms": 2100, "cost_inr": 0.026}

GET/v1/serverless/

List your serverless endpoints and their current worker counts.

DELETE/v1/serverless/{name}

Delete an endpoint. Running workers are stopped.

🔔 Webhooks

Get HTTP callbacks when instance/billing events happen. GridShare signs every request with HMAC-SHA256.

POST/webhooks/

{
  "url": "https://myserver.com/gridshare-hook",
  "label": "production",
  "events": ["instance.started", "instance.stopped", "billing.low_balance"]
}

# Verify webhook signature (Python)
import hashlib, hmac

def verify_signature(secret: str, body: bytes, sig_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig_header)

# X-GridShare-Signature header contains: "sha256=<hex>"

Event types

Event	Trigger
instance.started	Container is running, SSH is ready
instance.stopped	Instance terminated (any reason)
instance.preempted	Instance stopped early because the provider node went offline or stopped sharing
instance.preemption_warning	Provider node is going offline — checkpoint/save now (work also auto-saves)
instance.migrated	Instance auto-migrated to a new GPU after node failure (payload has new SSH details)
billing.low_balance	Wallet below your alert threshold
billing.zero_balance	Wallet hit ₹0, instances stopped
serverless.cold_start	Serverless endpoint scaled up from zero

💰 Wallet & Billing

GET/buyers/me

Get account info including wallet balance, email, GSTIN, plan.

PATCH/buyers/me/budget-alert

Set spending alert threshold. Get WhatsApp + email when wallet drops below this.

{"alert_threshold_inr": 200}
# When balance < ₹200, you get alerted. Set to 0 to disable.

GET/buyers/billing/history

Get billing history (last 90 days). Each entry has instance ID, duration, cost, GPU tier.

GET/buyers/billing/invoice/{month}

Download GST invoice PDF for a given month (YYYY-MM format).

🏢 Organizations (Team Accounts)

Share a single wallet across a team. Up to 5 members, with admin/member roles. All billing under one GST invoice.

POST/orgs/

Create an org. Converts your account to an org admin wallet.

POST/orgs/{id}/invite

Invite a member by email. They get a join link.

GET/orgs/{id}/members

List members, their roles, and spend this month.

📓 JupyterLab Guide

Every instance launched with the jupyter template (or any PyTorch/TF template) exposes JupyterLab in-browser.

# Launch Jupyter instance
gridshare instances launch --gpu Standard --template jupyter

# Open in browser (auto-authenticates)
gridshare jupyter inst_xxx
# OR: visit https://gridshare.in/jupyter/inst_xxx in your dashboard

JupyterLab access is proxied through gridshare.in — no port forwarding needed. Works behind corporate firewalls.

💾 Network Volumes Guide

Persistent SSD volumes that survive instance restarts. Attach to any GPU in the same region. ₹6/GB/month.

# Create a volume
gridshare volumes create --name my-models --size 50 --region bangalore
# → volume_id: vol_abc123, 50 GB SSD, ₹400/month

# Attach to an instance
gridshare instances launch --gpu Ultra --template pytorch \
  --volume vol_abc123:/workspace/models

# In the container: /workspace/models persists across stops/restarts
# Use it to store model weights, datasets, checkpoints

Network Volumes are in active beta. Available to all users — create via dashboard or CLI. Volumes in one city cannot be attached to GPUs in a different city.

🛡 Resilience & Auto-Migration Guide

GridShare runs on consumer hardware owned by independent providers — nodes can and do go offline. The platform is built to make that survivable instead of pretending it never happens.

Auto-checkpointing

Instances with checkpointing enabled save workload state automatically:

Trigger	Behaviour
interval	Periodic checkpoint every 5 minutes by default — configurable per instance from 1 minute upward
shutdown_signal	Event-triggered save when the container receives a shutdown signal — provider stop or node going offline gracefully

Checkpoints are stored off-node, so they survive the death of the machine that produced them.

Auto-migration on node death

If the node running your instance stops responding, GridShare automatically:

Re-dispatches your workload

A replacement GPU with matching specs is found and your instance is re-created on it. If a checkpoint exists, work resumes from the last save.

Stops billing at the failure

You are not billed for any time after the node's last heartbeat, and your job is automatically moved at no cost — no support ticket needed.

Notifies you on every channel

Email, webhook (instance.migrated) and WhatsApp — including the new SSH details, so scripts and humans both know where the instance went.

If no replacement GPU is available, the instance is stopped honestly, billing ends at the node's last heartbeat, and you're told — it never sits showing "running" against a dead node.

Resilience strip in the dashboard

Each instance card in the dashboard shows a resilience strip: checkpointing status, time since last checkpoint, and migration history. Use it to confirm your training run is actually protected before you walk away for the night.

Subscribe to instance.preemption_warning and instance.migrated webhooks (see Webhooks) to checkpoint application state and re-point clients automatically.

⚖️ Acceptable Use

GridShare GPUs are for ML training, inference, rendering, and general compute. Cryptocurrency mining and other prohibited workloads are not allowed on any tier.

⚠️ Workloads are monitored using metadata only (GPU utilisation patterns, power draw, network signatures) — we never inspect your code, data, or container contents. Instances detected running crypto mining or other prohibited workloads are terminated without refund, and repeat offences lead to account closure. See the full list in our Terms of Service.