Agent API · Machine-readable access
Look up a real prompt before your agent generates.
This API does one thing: hand your agent cases and full prompts whose sources have been checked by a human. Start without a key; ask for one when your volume grows.
Backward compatible
Existing callers keep working
This API has always been anonymous and open, and it still is. Requests without an auth header return the same data as before, now under a soft per-IP rate limit. Anyone already running the goodcase Skill needs to change nothing. Only credentials starting with gc_ are treated as an API key, so an unrelated Authorization header will never get you rejected.
Three endpoints, all GET
The GoodCase Agent API: anonymous access works out of the box, API keys raise the daily quota, and every case ships a verifiable provenance claim.
GET /api/public/cases · Case list
curl -s "https://goodcase.ai/api/public/cases?category=video&take=3&locale=en"Query parameters
- category
- image / video / web / copy / hardware; anything else returns 400.
- q
- Keyword across title, summary, creator, recommended models, source, tags, and prompt text. Case-insensitive. Expands Chinese/English synonyms (e.g. 千问 → Qwen). With q, results are relevance-ranked rather than filtered in default order: items[0] is the best match, not the hottest case. q is truncated to 200 chars / 12 whitespace-separated terms (no error).
- take
- 1–50 items, defaults to 20, out-of-range values are clamped.
- locale
- Content language: zh-CN or en. Defaults to zh-CN.
- form
- Secondary form filter: text-to-video / ref-to-video / web-ui / motion-3d / game-3d / agent-tool. Anything else returns 400.
- exclude
- Exclude one or more forms, comma-separated (same values as form). Unknown values are silently dropped.
- sample
- Deterministic random sample size, 1–50, out-of-range values are clamped. Overrides take when present.
- seed
- Sampling seed, used with sample. Same seed + same params reproduces the same batch next call; omit it for a random draw, and the seed actually used is echoed back in the response.
GET /api/public/cases/{slug} · Full case
curl -s "https://goodcase.ai/api/public/cases/real-case-01-umesh-ai?locale=en"On top of the list fields, this returns promptFull, editorNote, labNote, spreadScore, and sourceHeatNote.
With an API key
curl -s -D - \
-H "Authorization: Bearer gc_xxxxxxxxxxxx" \
"https://goodcase.ai/api/public/cases?take=3"GET /api/public/cases/{slug}/retests · Retest evidence
curl -s "https://goodcase.ai/api/public/cases/real-case-01-umesh-ai/retests?locale=en"Returns this case's on-site per-model retest records — stabilityScore, evidenceLevel, per-model latest/history, and the full record list. Use it to compare a model you just tested against the site's own baseline.
Model eval: test any new model with the same set
The day a new model ships, an agent with the goodcase Skill installed can sample cases by category and run them, then compare against the site's own retest baseline.
- 01Sample: GET /api/public/cases?category=web&form=web-ui&sample=5&seed=20260906-yourmodel. Defaults to exclude=motion-3d — background video / 3D tests the asset, not the model. Same seed, same result, so recording the seed makes it reproducible.
- 02Pull the baseline: GET /api/public/cases/{slug} for promptFull, GET /api/public/cases/{slug}/retests for the site's own per-model retest records.
- 03Run and compare: run promptFull on the target model, record reproduced / degraded / failed per case, and output a comparison table plus a goodcase-model-eval-v1 JSON list — the seed + slug list is what lets a later on-site retest line up against this same batch.
curl -s "https://goodcase.ai/api/public/cases?category=web&form=web-ui&sample=5&seed=20260906-yourmodel"Try saying
benchmark this model with goodcase
test Kimi K3 with goodcase
sample 10 video cases and run an evalA self-run result is not an official goodcase retest; finalScore (judge score) and stabilityScore (human review tier) are not on the same scale.
Install the Skill first
npx skills add LearnPrompt/goodcase-lite --skill goodcase --global --copy --yes --full-depthResponse sample (truncated)
{
"count": 1,
"locale": "zh-CN",
"items": [
{
"slug": "tattoo-generator",
"title": "Tattoo Generator",
"category": "video",
"source": "Comfy Workflows",
"sourceUrl": "https://comfy.org/workflows/90d086fef9e3-90d086f…",
"creator": "Rob",
"summary": "这条工作流没有花哨的效果，胜在把纹身设计的沟通痛点解决得很实际…",
"promptPreview": "Turn your tattoo design ideas into reality with …",
"mediaType": "video",
"mediaUrl": "https://…public.blob.vercel-storage.com/…",
"posterUrl": "https://…public.blob.vercel-storage.com/…",
"stabilityScore": 0,
"recommendedModels": ["ComfyUI"],
"costBand": "medium",
"evidenceLevel": "L1",
"tags": ["source-comfy", "workflow-method", "not-rerun"],
"url": "https://goodcase.ai/cases/tattoo-generator",
"contentLocale": "en",
"availableLocales": ["zh-CN"],
"isFallback": false,
"provenance": {
"sourceUrl": "https://comfy.org/workflows/90d086fef9e3-90d086fef9e3/",
"verifiedAgainstSource": true,
"method": "human-reviewed-source-match",
"policyEffectiveAt": "2026-08-05",
"note": "已发布案例的 prompt 均经人工核对与原帖一致…"
},
"likedCount": 0,
"retestVoteCount": 0
}
]
}Every case carries a checkable source claim
Training data is full of prompts that read like expert work and were never actually run. Every case we publish must be checked by a human against the original post, and prompts a platform reverse-engineered from the output image are rejected outright. That rule has governed all published content since 2026-08-05; it now appears as a structured field so an agent can read it instead of taking our word for it.
provenance
- sourceUrl
- The original post. Null when no public source exists.
- verifiedAgainstSource
- Whether the prompt was human-checked against the source. False when there is no source — nothing to check against, so no claim.
- method
- Verification method id. Treat unknown future values as unverified.
- policyEffectiveAt
- When the provenance rule took effect, not a per-case timestamp.
- note
- A human-readable sentence, in the requested locale.
Two tiers, one set of headers
The anonymous tier is a soft limit. The API runs on serverless functions, each instance keeps its own in-memory window, so the effective allowance is higher than the stated number and resets when an instance recycles. It exists to catch a runaway loop, not to meter usage. Real metering lives on API keys, is counted in the database, and resets at 00:00 UTC.
| Tier | Quota | How |
|---|---|---|
| No key | 60 req / hour / IP | Nothing to do — just curl. |
| With key | 2,000 req / day by default, raised on request | Authorization: Bearer gc_xxx, or X-API-Key: gc_xxx. |
Rate limit headers
- X-RateLimit-Limit
- Ceiling for your current tier.
- X-RateLimit-Remaining
- Calls left in this window or day.
- X-RateLimit-Reset
- Reset time, Unix seconds.
- X-RateLimit-Scope
- anonymous or key — confirms whether your key took effect.
- Retry-After
- Only on 429; suggested wait in seconds.
Error codes
- 400
- Invalid parameter, e.g. an unknown category.
- 401
- A gc_ credential that is invalid or revoked. Drop it to fall back to the anonymous tier.
- 404
- No such slug.
- 429
- Soft rate limit or daily quota exhausted; see Retry-After.
v1 keys are issued by hand
There is no self-serve signup yet. We would rather issue the first batch manually, learn who is calling and what quota actually makes sense, and only then decide whether a signup flow is worth building.
- 01Tell us your use case, rough daily volume, and how to reach you.
- 02We issue the key and send the plaintext privately. It is shown once; we store only a hash.
- 03Put it in the Authorization header. Nothing else about your calls changes.
Skip the plumbing: install the Skill
The goodcase Skill wraps this API in natural-language queries and works across Claude Code, Codex CLI, Cursor, and Gemini CLI. One line:
npx skills add LearnPrompt/goodcase-lite --skill goodcase --global --copy --yes --full-depthThen ask your AI what good cases are new, and it will look them up instead of inventing one from training data.