Skip to content

api-documentation.md

Latest commit

 

History

History
131 lines (103 loc) · 4.03 KB

api-documentation.md

File metadata and controls

131 lines (103 loc) · 4.03 KB
Raw

API

Base URL of the demo: https://codeforge-euxv.onrender.com (free instance: the first request after a quiet period takes about a minute). JSON in and out; no authentication yet.

Method Path Purpose
GET /health liveness: OK
GET /health/details sandbox mode, worker count, queue size
GET /cf/{contestId}/{index} fetch a Codeforces problem: statement, limits, samples
POST /problems/import store a problem and its sample tests
GET /problems list stored problems
POST /submit queue a submission
GET /submission/{id} verdict, metrics and per-test results
GET /submissions the 200 most recent submissions

Responses below are real ones from the demo.

GET /health/details

{ "status": "OK", "role": "all", "sandbox": "process", "workers": 1, "queued": 0, "running": 0 }

role is api, worker or all; sandbox is docker or process.

GET /cf/{contestId}/{index}

GET /cf/255/A

{
  "title": "A. Greg's Workout",
  "statement": "Greg is a beginner bodybuilder. ...",
  "inputSpec": "Input The first line contains integer n (1 ≤ n ≤ 20). ...",
  "outputSpec": "Output Print word \"chest\" ...",
  "timeLimit": "2 seconds",
  "memoryLimit": "256 megabytes",
  "samples": [ { "input": "2\n2 8", "output": "biceps" }, { "input": "3\n5 1 10", "output": "back" } ]
}

The client turns timeLimit and memoryLimit into milliseconds and megabytes for the import.

POST /problems/import

{
  "title": "A. Greg's Workout",
  "description": "Greg is a beginner bodybuilder. ...",
  "timeLimitMs": 2000,
  "memoryLimitMb": 256,
  "samples": [ { "input": "2\n2 8", "output": "biceps" } ]
}

Response: { "problemId": 78 }

Status When
400 time limit outside 100-15000 ms or memory limit outside 16-1024 MB
413 more than 100 samples or an oversized statement
429 more than 30 imports per minute from one client

POST /submit

{ "problemId": 78, "language": "cpp", "code": "#include <bits/stdc++.h>\n..." }

language is cpp, java or python. Java may use any public class name. Response:

{ "submissionId": 51, "status": "QUEUED" }
Status When
400 unsupported language
413 source larger than 64 KB
429 more than 10 submissions per minute from one client (SUBMITS_PER_MINUTE)
503 50 or more submissions waiting (MAX_QUEUED)

GET /submission/{id}

Poll until verdict is no longer QUEUED or RUNNING.

{
  "id": 51,
  "verdict": "WRONG_ANSWER",
  "output": "biceps",
  "runtimeMs": 3,
  "memoryKb": 9536,
  "testResults": [
    { "testNumber": 1, "passed": true,  "expected": "biceps", "received": "biceps", "status": "OK", "timeMs": 3, "memoryKb": 9528 },
    { "testNumber": 2, "passed": false, "expected": "back",   "received": "biceps", "status": "WA", "timeMs": 3, "memoryKb": 9536 }
  ],
  "problemId": 78,
  "problemTitle": "A. Greg's Workout",
  "totalTests": 3,
  "timeLimitMs": 2000,
  "memoryLimitMb": 256
}
  • Judging stops at the first failing test, so testResults can be shorter than totalTests; the rest were not run.
  • runtimeMs and memoryKb are the maximum CPU time and peak memory over the tests that ran, measured for the program itself.
  • Per-test status: OK, WA, TLE, MLE, OLE, RE.
  • output: the program's output for WRONG_ANSWER, the compiler message for COMPILE_ERROR, the exit code or signal plus stderr for RUNTIME_ERROR.
  • 404 for an unknown id.

Verdicts: QUEUED, RUNNING, ACCEPTED, WRONG_ANSWER, TLE, MEMORY_LIMIT_EXCEEDED, OUTPUT_LIMIT_EXCEEDED, RUNTIME_ERROR, COMPILE_ERROR, INTERNAL_ERROR.

GET /submissions

[
  {
    "id": 51, "language": "cpp", "verdict": "WRONG_ANSWER", "createdAt": "2026-10-08T17:09:34",
    "problemId": 78, "problemTitle": "A. Greg's Workout", "runtimeMs": 3, "memoryKb": 9536
  }
]

Newest first, at most 200. createdAt is Indian Standard Time; the database stores UTC.