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.
Two endpoints, both 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, and creator. Case-insensitive.
- take
- 1–50 items, defaults to 20, out-of-range values are clamped.
- locale
- Content language: zh-CN or en. Defaults to zh-CN.
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"Response 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/goodcaseai --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.