API Reference

Integrate Evals.sh directly into your CI/CD pipelines, LMS systems, or automated grading platforms using our REST API.

Authentication

All API requests must be authenticated using your Secret API Key. Pass your key in the standard HTTP Authorization header as a Bearer token.

Authorization: Bearer eval_sk_...

POST/api/code-review

Submit Code for Review

Enqueues a background AI task to analyze a snippet of code or remote files. Use the returned ID to poll for the evalScore.

Request Body

{
  "code": "function sum(a,b) { return a+b; }", // Optional piece of code text
  "instruction": "Check for edge cases",        // Optional evaluation guidelines
  "fileUrls": [                                 // Optional remote file URLs to scan
    "https://raw.githubusercontent.com/user/repo/main/src/index.ts"
  ]
}

Response Data (202 Accepted)

{
  "codeReviewId": "uuidv4",
  "message": "Code review queued successfully"
}

GET/api/code-review/:id/stream

Stream Review Progress (SSE)

Subscribe to a Server-Sent Events stream to receive real-time updates as the AI generates diffs and evaluates chunks.

Event Payloads

// type: "progress" — Emitted as chunks are processed

{ "type": "progress", "processedChunks": 2, "totalChunks": 5 }

// type: "completed" — Final success event

{ "type": "completed", "review": { ...CodeReviewResult } }

// type: "failed" — Critical failure event

{ "type": "failed", "review": { "codeReviewId": "...", "status": "failed" } }

GET/api/code-review/:id

Poll for Results

Fetch the status of an ongoing review. Once the status transitions to completed, the full data including the evalScore is returned.

Response Data (200 OK)

{
  "id": "uuidv4",
  "type": "code-review",
  "status": "completed",
  "title": "src/index.ts",
  "evalScore": 85,
  "createdAt": "2024-03-22T10:00:00Z",
  "completedAt": "2024-03-22T10:01:05Z",
  "data": { "files": [...] },
  "codeReviewId": "uuidv4"
}