API Reference

The Grader.io REST API allows you to programmatically manage graders, submit data, and retrieve results.

Base URL

https://api.grader.io/v1

Authentication

All API requests require a Bearer token in the

Authorization

header:

Authorization: Bearer YOUR_API_KEY

Generate API keys from Dashboard → Connections → API Keys.

Rate Limits

Plan	Requests/min	Requests/day
Starter	60	10,000
Pro	120	50,000
Elite	300	200,000

Endpoints

Submissions

Create Submission

POST /submissions

Request Body:

{
  "graderId": "string",
  "data": {
    "field1": "value1",
    "field2": "value2"
  },
  "metadata": {
    "source": "website",
    "referrer": "https://example.com"
  }
}

Response:

{
  "id": "sub_abc123",
  "graderId": "grd_xyz789",
  "score": 85,
  "category": "hot",
  "criteria": [
    {
      "name": "Budget",
      "score": 25,
      "maxScore": 30,
      "details": "Budget of $50,000 exceeds threshold"
    }
  ],
  "createdAt": "2025-04-15T14:22:17.910Z"
}

List Submissions

GET /submissions?graderId=grd_xyz789&limit=20&offset=0

Query Parameters:

Parameter	Type	Default	Description
`graderId`	string	—	Filter by grader ID
`limit`	integer	20	Max results (1-100)
`offset`	integer	0	Pagination offset
`status`	string	—	Filter: `pending` , `graded` , `error`
`category`	string	—	Filter: `hot` , `warm` , `cold` , `disqualified`

Get Submission

GET /submissions/:id

Graders

List Graders

GET /graders

Get Grader

GET /graders/:id

Create Grader

POST /graders

Request Body:

{
  "name": "Lead Qualifier",
  "description": "Evaluates inbound leads",
  "criteria": [
    {
      "name": "Budget",
      "type": "numeric",
      "weight": 30,
      "config": {
        "field": "budget",
        "ranges": [
          { "min": 0, "max": 5000, "score": 10 },
          { "min": 5000, "max": 25000, "score": 20 },
          { "min": 25000, "max": null, "score": 30 }
        ]
      }
    }
  ],
  "categories": [
    { "name": "hot", "minScore": 80 },
    { "name": "warm", "minScore": 50 },
    { "name": "cold", "minScore": 20 },
    { "name": "disqualified", "minScore": 0 }
  ]
}

Webhooks

Register Webhook

POST /webhooks

{
  "url": "https://your-server.com/webhook",
  "events": ["submission.graded", "submission.created"],
  "secret": "your-webhook-secret"
}

Webhook Payload

When an event fires, we send a POST request to your URL:

{
  "event": "submission.graded",
  "timestamp": "2025-04-15T14:22:17.910Z",
  "data": {
    "submissionId": "sub_abc123",
    "graderId": "grd_xyz789",
    "score": 85,
    "category": "hot"
  }
}

Verify webhooks using the

X-Grader-Signature

header with your secret.

Error Codes

Code	Description
`400`	Bad Request — Invalid parameters
`401`	Unauthorized — Invalid or missing API key
`403`	Forbidden — Insufficient permissions
`404`	Not Found — Resource doesn't exist
`429`	Rate Limited — Too many requests
`500`	Server Error — Something went wrong

Error Response Format:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "The 'graderId' field is required",
    "details": {}
  }
}

Need help with the API? Contact Support

Documentation