API Documentation

Overview

localmaxxing provides public marketplace and local LLM benchmark APIs. Partner sites, agents, and developers can:

1. Run inference speed tests on models
2. Collect performance metrics (tok/s, TTFT, peak VRAM, etc.)
3. Submit results to POST /api/speed-tests
4. Query leaderboard data and speed test results
5. Display active marketplace ads that link visitors back to LocalMaxxing

Authentication

Submitting speed tests requires authentication. Two methods are supported:

1. Bearer API Key (recommended for agents)

Include your API key in the Authorization header:

Authorization: Bearer bhk_<40 hex chars>

2. Session Cookie

If you're calling the API from the browser (e.g., the submit form), your session cookie authenticates you automatically.

Example

curl -X POST https://www.localmaxxing.com/api/speed-tests \
  -H "Authorization: Bearer bhk_1a2b3c4d5e6f7890abcdef1234567890abcdef12" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Agent Metadata

Agents should call GET /api/agent-context before submitting. It returns accepted enum values, schemas, examples, methodology tips, and endpoint URLs in one cached response.

The machine-readable OpenAPI 3.1 spec is available at GET /api/openapi.json.

Marketplace Feed

Use the public marketplace feed to display active LocalMaxxing hardware listings on a partner site. No API key is required. Listing and contact actions link back to the original ad on LocalMaxxing.

Quick start

curl --fail "https://www.localmaxxing.com/api/marketplace/feed?limit=20"

Query parameters

Response

{
  "listings": [
    {
      "id": "listing-id",
      "title": "RTX 3090 workstation",
      "description": "Ready for local inference.",
      "condition": "USED",
      "priceUsd": 1250,
      "currency": "USD",
      "hardwareDetails": "RTX 3090, Ryzen 9, 64 GB RAM",
      "seller": {
        "username": "seller",
        "displayName": "Seller Name",
        "profileUrl": "https://www.localmaxxing.com/en/user/seller"
      },
      "images": [
        {
          "id": "image-id",
          "url": "https://www.localmaxxing.com/api/marketplace/images/image-id/content",
          "thumbnailUrl": "https://www.localmaxxing.com/api/marketplace/images/image-id/content?variant=thumb",
          "contentType": "image/webp",
          "width": 1600,
          "height": 1067,
          "sortOrder": 0
        }
      ],
      "benchmarkRuns": [],
      "listingUrl": "https://www.localmaxxing.com/en/marketplace/listing-id",
      "contactUrl": "https://www.localmaxxing.com/en/marketplace/listing-id",
      "createdAt": "2026-08-01T12:00:00.000Z",
      "updatedAt": "2026-08-02T12:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "nextCursor": null,
    "hasMore": false
  },
  "generatedAt": "2026-08-06T12:00:00.000Z"
}

Fetch every page

async function fetchMarketplace() {
  const listings = [];
  let cursor = null;

  do {
    const url = new URL("https://www.localmaxxing.com/api/marketplace/feed");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const response = await fetch(url);
    if (!response.ok) throw new Error(`LocalMaxxing returned ${response.status}`);

    const page = await response.json();
    listings.push(...page.listings);
    cursor = page.pagination.hasMore ? page.pagination.nextCursor : null;
  } while (cursor);

  return listings;
}

Render an ad

const image = listing.images[0];

return (
  <a href={listing.listingUrl} target="_blank" rel="noopener noreferrer">
    {image && <img src={image.thumbnailUrl} alt={listing.title} loading="lazy" />}
    <h2>{listing.title}</h2>
    <p>{new Intl.NumberFormat("en-US", {
      style: "currency",
      currency: listing.currency
    }).format(listing.priceUsd)}</p>
    <span>View on LocalMaxxing</span>
  </a>
);

Get one listing

Returns { "listing": { ... } } for an active listing. A 404 means the listing is missing or no longer active.

Images and benchmarks

Use thumbnailUrl for cards and url for larger views. The URLs are cross-origin compatible, hide the underlying blob provider, and are safe to cache. The benchmarkRuns array contains approved proof-of-performance runs only and may be empty.

POST /api/speed-tests

Submit a speed test result. Requires authentication. This is the primary endpoint for agents.

Required Fields

tokSOut is required. Additional metrics are optional:

Optional Fields

Responses

{
  "id": "clxyz...",
  "modelId": "...",
  "hardwareId": "...",
  "engineId": "...",
  "userId": "...",
  "tokSOut": 87.4,
  "tokSPrefill": 1210.5,
  "status": "APPROVED",
  "createdAt": "2026-04-14T03:45:00.000Z",
  "model": { "hfId": "Qwen/Qwen3-8B", "displayName": "Qwen3-8B", ... },
  ...
}

{
  "error": "Validation failed",
  "details": {
    "fieldErrors": { "hardware.vramGb": ["Required"] },
    "formErrors": []
  }
}

{ "error": "Authentication required. Use a session cookie or Authorization: Bearer <api_key>" }

{ "error": "Model \"some/bad-id\" not found on HuggingFace" }

{
  "error": "Rate limit exceeded. You may submit once every 1 minute.",
  "retryAfterMs": 45000,
  "lastSubmittedAt": "2026-04-14T03:40:00.000Z"
}

POST /api/speed-tests/dry-run

Validate a speed test payload without writing to the database or consuming the rate limit. Requires the same Bearer API key or session cookie auth as real submissions.

{
  "valid": true,
  "parsed": { "hfId": "Qwen/Qwen3-8B", "modelRevision": "main", "promptTokens": 0 }
}

Hardware Object

The hardware field is a discriminated union on hwClass. Use the right shape for the hardware being tested.

{
  "hwClass": "DISCRETE_GPU",
  "gpuName": "RTX 3090",
  "gpuCount": 1,
  "vramGb": 24,
  "cpu": "Ryzen 9 5900X",
  "ramGb": 64,
  "os": "Ubuntu 22.04",
  "powerWatts": 350
}

{
  "hwClass": "UNIFIED",
  "chipVendor": "Apple",
  "chipFamily": "M4",
  "chipVariant": "M4 Pro",
  "unifiedMemoryGb": 48,
  "npuTops": 38,
  "os": "macOS 15.4"
}

{
  "hwClass": "CPU_ONLY",
  "cpu": "Intel Xeon W9-3595X",
  "ramGb": 512,
  "os": "Ubuntu 24.04"
}

Engine Flags Object

Optional. Provide engineFlags to record the exact launch configuration. If supplied, commandSnippet is required and explicit fields override parsed command flags.

{
  "commandSnippet": "llama-server -m Qwen3-8B-Q4_K_M.gguf -c 8192 --n-gpu-layers 99 -fa",
  "tensorParallel": 1,
  "gpuLayers": 99,
  "kvCacheDtype": "q8_0",
  "flashAttn": true,
  "attentionBackend": "flash_attn",
  "concurrency": 4,
  "temperature": 0.6,
  "topP": 0.95
}

GET /api/speed-tests

Fetch approved speed test results. Public endpoint — no auth required.

Query Parameters

Response

{
  "benchmarks": [ { ...benchmarkRun, model: {...}, hardware: {...}, engine: {...}, engineFlags: {...}, user: {...} } ],
  "total": 142,
  "limit": 20,
  "offset": 0
}

Example

curl "https://www.localmaxxing.com/api/speed-tests?hfId=Qwen/Qwen3-8B&hwClass=DISCRETE_GPU&limit=10"
curl "https://www.localmaxxing.com/api/speed-tests?username=mason&dateFrom=2026-04-01T00:00:00Z"

GET /api/leaderboard

Fetch ranked leaderboard data. Public endpoint — no auth required. Results are sorted by tokSOut descending.

Query Parameters

Response

{
  "rows": [ { rank, id, model, hardware, engine, engineFlags, user, tokSOut, ... } ],
  "total": 89,
  "limit": 50,
  "offset": 0
}

GET /api/models

Browse models in the database. Public endpoint — no auth required.

Query Parameters

GET /api/models/search

Resolve fuzzy model names to canonical HuggingFace IDs before submitting. Query with q and optional limit (1–25, default 10). Response entries include hfId, displayName, family, params, and benchmarkCount.

Benchmarks API

Quality benchmarks use approved suites with task-level results and server-side aggregate scoring. Benchmark runs start as PENDING and appear publicly after admin approval.

API Keys

Manage API keys for programmatic access. All endpoints require session authentication (not API key auth). Maximum of 10 keys per account.

[
  { "id": "...", "name": "My Agent", "prefix": "bhk_1a2b", "createdAt": "...", "lastUsedAt": "...", "expiresAt": null },
  ...
]

{
  "name": "My Agent Key",
  "expiresAt": "2027-01-01T00:00:00Z"  // optional ISO-8601
}

{
  "id": "...",
  "name": "My Agent Key",
  "prefix": "bhk_1a2b",
  "createdAt": "...",
  "expiresAt": "2027-01-01T00:00:00Z",
  "key": "bhk_1a2b3c4d5e6f7890abcdef1234567890abcdef12"  // SHOWN ONLY ONCE
}

Saved Setups

Manage saved hardware/engine configurations. All endpoints require session authentication and ownership verification.

{
  "name": "My RTX 3090 Setup",
  "description": "Standard llama.cpp config",
  "isDefault": true,
  "hwClass": "DISCRETE_GPU",
  "gpuName": "RTX 3090",
  "gpuCount": 1,
  "vramGb": 24,
  "engineName": "llama.cpp",
  "quantization": "Q4_K_M",
  "gpuLayers": 99,
  "flashAttn": true,
  "contextLength": 8192
}

Rate Limits

Common Engine Names

Use consistent casing — these are the accepted values:

Benchmark Methodology

For reproducible, trustworthy results:

• Warm up the model with 1–2 throwaway runs before recording
• Use a fixed prompt for comparability — a 512-token system prompt + 32-token user message is a good baseline
• Record steady-state throughput — not the first token burst
• Measure tokSPrefill as prompt/input processing throughput before generation; this helps estimate wait time for long prompts
• Measure peakVramGb via nvidia-smi or equivalent at peak load
• Measure gpuPowerWatts per GPU via nvidia-smi --query-gpu=power.draw --format=csv during sustained generation — one entry per physical card
• Report hardwareCost if you know what you paid — choose canonical component names from hardwareOptions.hardwareCostComponentNames so cost/performance comparisons can filter and link hardware correctly
• Report batchSize accurately — batch=1 and batch=8 are not comparable
• Set temperature: 0 (greedy decode) for deterministic throughput benchmarks unless testing sampling overhead
• Include commandSnippet — the exact launch command is the most useful thing for reproducibility

Field Constraints

Examples

Minimal Submission

Smallest valid request body:

{
  "hfId": "Qwen/Qwen3-8B",
  "hardware": {
    "hwClass": "DISCRETE_GPU",
    "gpuName": "RTX 3090",
    "vramGb": 24
  },
  "engineName": "llama.cpp",
  "quantization": "Q4_K_M",
  "tokSOut": 87.4,
  "tokSPrefill": 1210.5,
  "ttftMs": 210
}

Full Submission

Complete request with all optional fields:

{
  "hfId": "Qwen/Qwen3-8B",
  "modelRevision": "main",
  "hardware": {
    "hwClass": "DISCRETE_GPU",
    "gpuName": "RTX 3090",
    "gpuCount": 1,
    "vramGb": 24,
    "cpu": "Ryzen 9 5900X",
    "ramGb": 64,
    "os": "Ubuntu 22.04"
  },
  "engineName": "llama.cpp",
  "engineVersion": "b5012",
  "quantization": "Q4_K_M",
  "backend": "cuda",
  "promptTokens": 512,
  "outputTokens": 1024,
  "contextLength": 8192,
  "batchSize": 1,
  "ttftMs": 142.5,
  "tokSOut": 87.4,
  "tokSPrefill": 1210.5,
  "tokSTotal": 74.1,
  "peakVramGb": 6.2,
  "gpuPowerWatts": [285.5, 310.2],
  "hardwareCost": [{ "component": "NVIDIA GeForce RTX 3090", "condition": "USED", "yearPurchased": 2021, "price": 700, "currency": "USD" }],
  "notes": "Automated benchmark via agent. Thermal throttling observed after 10 min.",
  "engineFlags": {
    "commandSnippet": "llama-server -m Qwen3-8B-Q4_K_M.gguf -c 8192 --n-gpu-layers 99 -fa --temp 0.6 --top-p 0.95",
    "gpuLayers": 99,
    "kvCacheDtype": "q8_0",
    "flashAttn": true,
    "prefixCaching": true,
    "temperature": 0.6,
    "topP": 0.95
  }
}

cURL — Submit Speed Test

curl -X POST https://www.localmaxxing.com/api/speed-tests \
  -H "Authorization: Bearer bhk_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "hfId": "Qwen/Qwen3-8B",
    "hardware": { "hwClass": "DISCRETE_GPU", "gpuName": "RTX 3090", "vramGb": 24 },
    "engineName": "llama.cpp",
    "quantization": "Q4_K_M",
    "tokSOut": 87.4,
    "tokSPrefill": 1210.5,
    "tokSTotal": 74.1,
    "ttftMs": 142.5,
    "contextLength": 8192,
    "engineFlags": {
      "commandSnippet": "llama-server -m Qwen3-8B-Q4_K_M.gguf -c 8192 --n-gpu-layers 99 -fa"
    }
  }'

cURL — Query Leaderboard

curl "https://www.localmaxxing.com/api/leaderboard?hwClass=DISCRETE_GPU&memTier=24&verified=true&limit=10"
curl "https://www.localmaxxing.com/api/leaderboard?hardwareName=RTX+4090&modelFamily=qwen&isMoE=false"

cURL — Filter Speed Tests by User & Date

curl "https://www.localmaxxing.com/api/speed-tests?username=mason&dateFrom=2026-04-01T00:00:00Z&dateTo=2026-04-30T23:59:59Z"