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 and label are required; a detail close-up is recommended), 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.

Connect GradeThread to Claude and run your pipeline from a conversation: ask what is unlisted, get drafts written, publish, reprice, end listings. It is a Model Context Protocol server, so it works in Claude Code, the Claude desktop and web apps, and anything else that speaks MCP.

Included on Pro ($59/mo) and Business ($99/mo). Pro includes 500 connector actions a month and Business 2,000; reading costs nothing and is not counted. The sandbox tools work on every plan, including Free, so you can see what it does before paying for it.

Adding it

In Claude Code:

claude mcp add --transport http gradethread https://functions.gradethread.com/mcp

In the Claude web or desktop app: Settings → Connectors → Add custom connector, then paste https://functions.gradethread.com/mcp. Either way you will be sent to GradeThread to sign in and choose what to allow.

What you are asked to allow

You can turn any of these off on the consent screen and still connect. A read-only connection is a normal thing to want.

The tools

Nothing that costs money or reaches a marketplace happens on one call. Grading, publishing, repricing, ending and relisting all preview first and then need a confirmation that is tied to the exact items and prices you were shown. If the price moves between the preview and the confirmation, the confirmation stops being valid and Claude has to show you the new one.

On Claude clients that support it, you are also asked directly \u2014 a prompt with a yes-or-no, not a message from Claude saying it asked you.

What it can spend. Grading uses your grading credits. Writing drafts uses one AI action per item. Publishing and repricing cost nothing themselves, but they change what buyers pay. Everything else is free to run.

The caps, which apply even when you confirm. Per hour: 20 publishes, 50 price changes, 20 listings ended. Per day: 200 grades. Per month: your plan's connector actions. And a price move over 25%, or below an item's cost basis, is refused outright \u2014 a confirmation is not a safety net for an arithmetic error.

Turning it off. Settings → API keys lists every connected application. Disconnecting one stops it immediately \u2014 not at the end of an hour, and not at the end of a session.

Every call is recorded. Each tool call is written to an audit log with the tool, the items it touched, whether it succeeded and why it was refused if it was \u2014 kept for 400 days. Ask support for your account's log if you ever need to reconstruct what happened.

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.