Grade-as-a-Service API

1. Create an API key. In your dashboard under Account → API keys (Business plan), create a key and grant only the scopes you need (submit, read, webhook_manage). The secret is shown once — store it safely. Rotate or revoke it anytime.
2. Try it free in the sandbox. Call /api/v1/sandbox/grades (below) — deterministic sample grades, zero credits, same shapes as production.
3. Go live. Drop the /sandbox path, attach real photos (front, back, label + a detail), and submit to /api/v1/grades. Poll /api/v1/grades/:id or receive a webhook.
4. Scale up. Grade up to 50 garments per call with /api/v1/grades/batch and let webhooks push each result as it finishes.

Every request authenticates with an API key in the X-API-Key header. Keys are created in your dashboard under Account → API keys (Business plan), are shown once, and can be scoped to read, submit, and webhook_manage. Rotate or revoke a key at any time. Base URL: https://functions.gradethread.com.

All responses share one envelope: { data, error, meta }.

Full machine-readable reference (OpenAPI 3.1) — openapi.json. No key required; import it into Postman, Insomnia, or your codegen of choice.

Grade up to 50 garments in one call. The batch is durable and async: you get a batch id back immediately, each garment is graded and charged independently (partial success is fine), and a grade.completed webhook fires per garment. Poll the batch-status endpoint for per-garment results. Every garment is validated the same way as a single grade — an invalid garment rejects the whole request up front. Prefer image URLs over base64 in a batch.

curl https://functions.gradethread.com/api/v1/grades/batch \
  -X POST \
  -H "X-API-Key: gt_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"garments":[
        {"title":"Denim jacket","garment_type":"outerwear","garment_category":"jacket",
         "images":[{"image_type":"front","url":"https://.../f.jpg"},
                   {"image_type":"back","url":"https://.../b.jpg"},
                   {"image_type":"label","url":"https://.../l.jpg"},
                   {"image_type":"detail","url":"https://.../d.jpg"}]}
      ]}'

# → 202 { "data": { "id": "<batch_id>", "status": "running", "item_count": 1 } }
# Poll GET /api/v1/grades/batch/<batch_id> for per-garment results.

Set a webhook URL with PATCH /api/v1/webhook (or in your dashboard). When a grade finalizes we POST a grade.completed event. Each delivery carries an X-GradeThread-Signature header — an HMAC-SHA256 (hex) of the raw request body, signed with your API key's secret hash — so you can verify authenticity. Failed deliveries retry with backoff (5s / 30s / 120s).

POST <your webhook_url>
X-GradeThread-Signature: <hex HMAC-SHA256 of the raw body>

{
  "event": "grade.completed",
  "data": {
    "submission_id": "…",
    "grade_report": { "id": "…", "overall_score": 8.5,
                      "grade_tier": "Excellent", "certificate_id": "…",
                      "finalized_at": "2026-07-09T…Z" }
  },
  "timestamp": "2026-07-09T…Z"
}

Build and test your integration with zero credits. The sandbox endpoints return deterministic sample grades — same auth, scopes, and response shape as production, so the only thing you change to go live is the URL path.

curl https://functions.gradethread.com/api/v1/sandbox/grades \
  -X POST \
  -H "X-API-Key: gt_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Vintage denim jacket","brand":"Levi'\''s"}'

Beyond grading, the API exposes GradeThread's proprietary Resale Condition Index as a queryable price guide: for a published brand-and-category item, the resale value range and sell-through at each condition-grade band. It's read-scoped and rate-limited like every other endpoint, with a free sandbox. Every figure is aggregate-only and sample-gated — items and bands without enough recent data are not returned rather than guessed.

curl https://functions.gradethread.com/api/v1/price-guide/patagonia-better-sweater \
  -H "X-API-Key: gt_sk_..."

# → { "data": { "slug": "patagonia-better-sweater", "brand": "Patagonia",
#       "bands": [ { "band": "high", "gradeRange": "8.5 – 10.0",
#                    "valueLowCents": 6500, "valueMedianCents": 8200,
#                    "valueHighCents": 9800, "sellThrough": 0.78 }, ... ] } }

A zero-dependency, typed client for Node and the browser.

npm install @gradethread/sdk

import { GradeThread } from "@gradethread/sdk";

const gt = new GradeThread({ apiKey: process.env.GRADETHREAD_API_KEY });

// Try it free in the sandbox (no credits spent):
const sample = await gt.sandbox.grades.create({ title: "Vintage denim jacket" });
console.log(sample.grade_report.overall_score); // e.g. 8.5

// Live grading:
const job = await gt.grades.create({
  title: "Vintage denim jacket",
  garment_type: "outerwear",
  garment_category: "jacket",
  images: [
    { image_type: "front", url: "https://.../front.jpg" },
    { image_type: "back", url: "https://.../back.jpg" },
    { image_type: "label", url: "https://.../label.jpg" },
    { image_type: "detail", url: "https://.../detail.jpg" },
  ],
});
const result = await gt.grades.get(job.id);

Limits are enforced per API key in a 60-second sliding window, with separate budgets for reads (GET) and writes (POST/PATCH). Exceeding a budget returns 429 with a retry_after_seconds hint. Live usage is shown on your dashboard.

Grading volume (quota) is metered by credits: each live grade spends 1 credit (Standard), 3 (Premium), or 5 (Express). Sandbox calls are free and never spend credits.

Render any grade certificate inside your own platform, under your brand. Set your company name, color, and logo in the dashboard and copy the generated <iframe> snippet — buyers see the grade in your brand with a small "Verified by GradeThread" trust mark.

API access, white-label embeds, and the developer dashboard are included in the Business plan ($99/mo). Grading is billed per grade via credits on top — see the pricing page for credit packs and per-grade tiers.