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 x-api-key header.

x-api-key: ak_...

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 results.

Request Body

{
  "code": "function sum(a,b) { return a+b; }",
  "instruction": "Check for edge cases and security",
  "fileUrls": [
    "https://raw.githubusercontent.com/user/repo/main/src/auth.ts"
  ]
}

Response Data (202 Accepted)

{
  "codeReviewId": "651f89c0-9f2b-4d44-9988-5928c52319aa",
  "message": "Code review queued successfully"
}

GET/api/code-review/:id

Poll Review Results

Fetch the complete status and results of a review job.

Response Data (200 OK)

{
  "codeReviewId": "651f89c0-9f2b-4d44-9988-5928c52319aa",
  "status": "completed",
  "evalScore": 85,
  "factorScores": {
    "security": "Good",
    "maintainability": "Excellent",
    "performance": "Good",
    "bestPractices": "Good"
  },
  "files": [
    {
      "filename": "src/auth.ts",
      "evalScore": 85,
      "factorScores": {
        "security": "Good",
        "maintainability": "Excellent",
        "performance": "Good",
        "bestPractices": "Good"
      },
      "diffs": [
        {
          "action": "replace",
          "startLine": 12,
          "endLine": 12,
          "explanation": "Use a more secure hashing algorithm for passwords.",
          "original": "const hashed = md5(password);",
          "fix": "const hashed = await bcrypt.hash(password, 10);",
          "contextBefore": [
            { "lineNumber": 10, "content": "import { md5 } from 'crypto';" }
          ],
          "contextAfter": [
            { "lineNumber": 13, "content": "return hashed;" }
          ]
        }
      ]
    }
  ],
  "createdAt": "2024-03-22T10:00:00Z",
  "completedAt": "2024-03-22T10:01:05Z"
}

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 evaluates chunks.

// Event: "progress"

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

// Event: "completed"

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

GET/api/code-review

List All Code Reviews

Returns a paginated list of all code reviews for the authenticated user.

Response Data (200 OK)

{
  "results": [
    {
      "codeReviewId": "651f89c0-9f2b-4d44-9988-5928c52319aa",
      "status": "completed",
      "title": "src/auth.ts",
      "evalScore": 85,
      "createdAt": "2024-03-22T10:00:00Z"
    },
    {
      "codeReviewId": "df12-9f2b-4d44-9988-5928c52319bb",
      "status": "failed",
      "title": "Pasted Code",
      "createdAt": "2024-03-21T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 42,
    "hasMore": true
  }
}

{ "codeReviewId": "651f89c0-9f2b-4d44-9988-5928c52319aa", "status": "completed", "evalScore": 85, "factorScores": { "security": "Good", "maintainability": "Excellent", "performance": "Good", "bestPractices": "Good" }, "files": [ { "filename": "src/auth.ts", "evalScore": 85, "factorScores": { "security": "Good", "maintainability": "Excellent", "performance": "Good", "bestPractices": "Good" }, "diffs": [ { "action": "replace", "startLine": 12, "endLine": 12, "explanation": "Use a more secure hashing algorithm for passwords.", "original": "const hashed = md5(password);", "fix": "const hashed = await bcrypt.hash(password, 10);", "contextBefore": [ { "lineNumber": 10, "content": "import { md5 } from 'crypto';" } ], "contextAfter": [ { "lineNumber": 13, "content": "return hashed;" } ] } ] } ], "createdAt": "2024-03-22T10:00:00Z", "completedAt": "2024-03-22T10:01:05Z" }

{ "results": [ { "codeReviewId": "651f89c0-9f2b-4d44-9988-5928c52319aa", "status": "completed", "title": "src/auth.ts", "evalScore": 85, "createdAt": "2024-03-22T10:00:00Z" }, { "codeReviewId": "df12-9f2b-4d44-9988-5928c52319bb", "status": "failed", "title": "Pasted Code", "createdAt": "2024-03-21T09:00:00Z" } ], "pagination": { "page": 1, "limit": 20, "total": 42, "hasMore": true } }