API Documentation

You are integrating with the LLM On Demand LLM Grid API — a distributed AI inference service.
The API lets you submit prompts to open-source LLMs (llama3, mistral, gemma, etc.) running on volunteer hardware.

## Authentication
All requests require a Bearer token in the Authorization header:
  Authorization: Bearer YOUR_API_KEY

## Base URL
  https://www.llmondemand.com/api/v1

## Submit an Inference Job
POST /v1/jobs
Content-Type: application/json

Body fields:
  model        (string, required)  — Ollama model name, e.g. "llama3:8b", "mistral:7b", "gemma:2b"
  prompt       (string, required)  — The prompt to run
  model_match  (string, optional)  — "exact" (default) or "family" to allow compatible model variants
  tag          (string, optional)  — Label for grouping usage stats (max 64 chars)
  webhook_url  (string, optional)  — URL to POST the completed result to (async callback)
  priority     (integer, optional) — Higher = processed sooner; defaults to your subscription's priority boost when omitted
  timeout_seconds (integer, optional) — Requeued for another worker if still claimed/running this long after being claimed, and failed if that keeps happening; defaults to 600 (10 minutes)
  max_price_credits (number, optional) — Max credits you will pay, held from your balance up front; the lowest worker ask wins and the rest is refunded. 0 (default) = free, done by volunteers

Success response (201):
{
  "job_id": "uuid",
  "status": "pending",
  "created_at": "2026-06-20T12:00:00Z"
}

Jobs are always accepted (201) as long as your API key is active — quota never blocks
submission, it only pauses processing (see "Token / Prompt Limits" below).

Error responses:
  422 — validation error (missing model/prompt, unsupported model, etc.)

## Poll Job Status
GET /v1/jobs/:id

Response when completed:
{
  "job_id": "uuid",
  "status": "completed",
  "output": "The model's response text...",
  "output_tokens": 142,
  "input_tokens": 34,
  "duration_ms": 8200,
  "completed_at": "2026-06-20T12:01:23Z"
}

Statuses: pending → claimed → running → completed | failed

## Webhook Callback (optional)
If you supply webhook_url, the API will POST to it on completion with the same payload as GET /v1/jobs/:id.

Every webhook request includes an X-LLMOnDemand-Signature header for verification:
  X-LLMOnDemand-Signature: sha256=

The signature is HMAC-SHA256 of the raw JSON body, keyed with your API key.
Verify it on your server before trusting the payload:

  Ruby:
    expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", YOUR_API_KEY, request.raw_post)
    halt 401 unless Rack::Utils.secure_compare(expected, request.env["HTTP_X_LLMONDEMAND_SIGNATURE"])

  Python:
    import hmac, hashlib
    expected = "sha256=" + hmac.new(api_key.encode(), request.data, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers["X-LLMOnDemand-Signature"]):
        abort(401)

  Node.js:
    const crypto = require("crypto");
    const expected = "sha256=" + crypto.createHmac("sha256", API_KEY).update(rawBody).digest("hex");
    if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) return res.sendStatus(401);

Always use a constant-time comparison to prevent timing attacks.

## List Jobs
GET /v1/jobs
Query params: status=completed|failed|pending, model=llama3:8b, tag=my-project, offset=0
An unrecognized status value returns 422 rather than silently matching nothing.
Response: { "jobs": [...], "total": 137, "offset": 0, "limit": 50 }

## Cancel a Job
DELETE /v1/jobs/:id          — cancel one pending job
DELETE /v1/jobs/cancel_all   — cancel all pending jobs

## Retry a Failed Job
POST /v1/jobs/:id/retry

## Increase or Decrease Priority
PATCH /v1/jobs/:id/priority
Body: { "priority": 10 }    — positive to increase, negative to decrease

## List Available Models
GET /v1/models
Returns array of models currently online in the grid with worker_count.

## Usage Statistics
GET /v1/usage
Returns token usage and job counts grouped by day/tag.

## Token / Prompt Limits
There are no per-model or per-request prompt length or output token limits.
Each model runs with its own baked-in context window on the worker's Ollama instance.
Rate limits are subscription-level quotas on total tokens used (daily/weekly/monthly).
Your current quota headroom is visible at GET /v1/usage.
If you exceed your quota, submission still succeeds — the job is accepted and stays
"pending" — but it will not be picked up by a worker until your quota resets.

## File Input (Blob Upload)
Blobs must be attached to an existing job. The required sequence is:

  1. Submit the job first:
     POST /v1/jobs   →  { "job_id": "uuid", ... }

  2. Create a blob slot for that job, describing the file you're about to send:
     POST /v1/blobs
     Body: { "job_id": "uuid", "blob_type": "image", "filename": "photo.png",
             "byte_size": 12345, "checksum": "",
             "content_type": "image/png" }
     Response: { "blob_id": "uuid", "upload_url": "https://...", "upload_headers": {...}, "expires_in": 300 }

  3. Upload the file directly to upload_url (PUT, no auth header, send upload_headers as-is):
     PUT    (binary body, headers from upload_headers)

  4. Confirm the upload:
     POST /v1/blobs/:blob_id/confirm
     Response: { "status": "confirmed" }

After confirmation the blob is attached to the job and visible to the assigned worker.
Supported blob_type values: "image" (default). Do NOT pass blob_ids in the job creation
payload — blobs must reference an existing job_id at creation time.

## Best Practices
- For fast responses use model_match "family" so the grid can route to any compatible variant.
- Supply a webhook_url for async flows instead of polling.
- Use the tag field to track usage per feature/project.
- Check GET /v1/models first to see which models are currently online before submitting.
- Prefer smaller models (7b–8b) for lower latency; use larger models only when quality demands it.
- Always verify X-LLMOnDemand-Signature on incoming webhooks using a constant-time comparison.