API Reference
Everything omegaUp's web frontend does, it does by calling the same public REST API you
can call yourself. Every page in the Arena, every scoreboard refresh, every submission is
an HTTP request to /api/... — so there is nothing the UI can do that the API can't.
Where the endpoint-by-endpoint reference lives
This page documents the cross-cutting rules that apply to every call — transport, authentication, and the response envelope. It deliberately does not list individual endpoints, because that list is generated from the source code and would rot the moment it were copied here by hand.
The authoritative, always-current surface is generated by
frontend/server/cmd/APITool.php
— the same tool that emits the typed frontend client
api.ts
and api_types.ts.
To see exactly what a controller accepts and returns, read the controller in
frontend/server/src/Controllers/
(each apiXxx method is one endpoint) or its generated docs, rather than a
hand-maintained table.
The rules that apply to every call
It's plain HTTP, GET or POST, JSON back. Every endpoint is invoked with an ordinary HTTP request and returns an appropriate HTTP status plus a JSON body. Read-only calls that need no privileges can be made with a GET — you can literally paste the URL into a browser and see the JSON.
HTTPS only — HTTP is refused, not downgraded silently. Because omegaUp cares about keeping users' data private and preventing cheating (someone sniffing contest traffic is a real threat, not a hypothetical one), the API is served exclusively over HTTPS. A call over plain HTTP does not quietly succeed: the server answers with an HTTP 301 permanent redirect to the secure URL, and a client that doesn't follow it gets nothing useful.
Every URL starts with the same prefix. All endpoints live under
https://omegaup.com/api/; the rest of the path selects the controller and method. By
convention we name endpoints by what comes after that prefix — so an endpoint written
here as time/get is really https://omegaup.com/api/time/get/.
Authentication is a token in a cookie called ouat. Most calls need no special
privilege, but the ones that act on your account require you to be logged in. Authenticate
by calling user/login, take the auth_token it returns, and send it on every subsequent
call as a cookie named ouat (omegaUp Auth Token). One important consequence, again
driven by anti-cheating: you may only have one active session at a time. If you log in
programmatically you invalidate your browser session, and vice-versa.
The response envelope
Every response is JSON and carries a status field. On success it is "ok"; on failure
it is "error" and the body also carries a machine-readable errorcode, a stable
errorname, and a human-readable, localized error message suitable for showing to a
user in their own language. Handle failures by branching on status/errorname, never by
matching on the human-readable error text — that text is translated and will change.
A worked example
The simplest possible call fetches the server's clock, which is handy for correcting a local clock that may be skewed:
$ curl https://omegaup.com/api/time/get/
{"time":1436577101,"status":"ok"}
It needs no privileges, so there's no ouat cookie, the status is HTTP 200 OK, and
time is a UNIX timestamp straight from the server's internal clock.
See also
- Useful Links — repositories, contribution guides, and the auto-generated controller docs.
- System Internals — how an API call to
run/createactually flows through\OmegaUp\ApiCallerinto a controller and on to the grader.