Loading...
Loading...
Generate a token from your dashboard at /dashboard/api
POST front/back images to /api/v1/grade
Poll GET /api/v1/grade/:id until status is "completed"
# Step 1: Submit a card for grading curl -X POST https://cardgrade.io/api/v1/grade \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -F "frontImage=@card_front.jpg" \ -F "backImage=@card_back.jpg" \ -F "gradingCompany=CGI" \ -F "cardType=Pokemon Card" # Step 2: Check grading status curl https://cardgrade.io/api/v1/grade/GRADING_ID \ -H "Authorization: Bearer YOUR_API_TOKEN"
Include your API token in the Authorization header of every request.
Authorization: Bearer cgrd_your_api_token_hereGenerate tokens in your dashboard. Tokens expire after 1 year. You can have up to 10 active tokens.
/api/v1/gradeSubmit a card for AI grading
| Name | Type | Required | Description |
|---|---|---|---|
| frontImage | File | Yes | Front image of the card (JPEG, PNG, or WebP, max 10MB) |
| backImage | File | No | Back image of the card |
| gradingCompany | string | No | Grading company standard (default: "CGI") |
| cardType | string | No | Card type (default: "Pokemon Card") |
| userNotes | string | No | Optional notes about the card |
{
"id": "abc123",
"status": "pending",
"creditsRemaining": 79
}/api/v1/grade/:idCheck grading status and retrieve results
| Name | Type | Required | Description |
|---|---|---|---|
| id | string (path) | Yes | Grading ID returned from POST /grade |
{
"id": "abc123",
"status": "completed",
"cardName": "Charizard VMAX",
"overallGrade": 9.2,
"results": {
"centering": 9.5,
"corners": 9.0,
"edges": 9.0,
"surface": 9.5,
"psaPrediction": 9,
"bgsPrediction": 9.0,
"cgcPrediction": 9.0
}
}/api/v1/gradesList your grading history with pagination
| Name | Type | Required | Description |
|---|---|---|---|
| limit | integer (query) | No | Results per page (1-100, default: 20) |
| offset | integer (query) | No | Pagination offset (default: 0) |
| status | string (query) | No | Filter by status: pending, processing, completed, failed |
{
"gradings": [
{ "id": "abc123", "status": "completed", "cardName": "Charizard", "overallGrade": 9.2, ... },
{ "id": "def456", "status": "pending", ... }
],
"limit": 20,
"offset": 0
}/api/v1/accountGet your account info, credits, and rate limits
{
"id": "user_123",
"plan": "pro",
"credits": 72,
"packCredits": 20,
"totalCredits": 92,
"rateLimits": {
"gradesPerMinute": 10,
"readsPerMinute": 50
}
}Rate limits are applied per user and vary by plan tier.
10 grades/min
50 read requests/min
30 grades/min
150 read requests/min
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests per minute |
| X-RateLimit-Remaining | Requests remaining in the current window |
| X-Request-Id | Unique request ID for debugging |
All error responses include an error message and a machine-readable code.
| Code | HTTP Status | Description |
|---|---|---|
| UNAUTHORIZED | 401 | Missing or invalid API token |
| FORBIDDEN | 403 | Account suspended or email not verified |
| PLAN_REQUIRED | 403 | API access requires an active Pro or Business plan |
| RATE_LIMITED | 429 | Too many requests — check X-RateLimit headers |
| INSUFFICIENT_CREDITS | 402 | No credits remaining — purchase a credit pack or upgrade |
| INVALID_INPUT | 400 | Missing or invalid request parameters |
| NOT_FOUND | 404 | Resource not found or not owned by you |
| INTERNAL_ERROR | 500 | Server error — retry or contact support |
# Example error response
{
"error": "Rate limit exceeded. Please try again later.",
"code": "RATE_LIMITED"
}