HotCRP REST API (2025-03-08:869208450)

Return a submission object specified by p, a submission ID.

All visible information about submission fields, tags, and overall status are returned in the paper response property, which defines a submission object. Error messages—for instance, about permission errors or nonexistent submissions—are returned in message_list.

Submission objects are formatted based on the submission form. They have an object property set to "paper", a pid, and a status. Other properties are provided based on which submission fields exist and whether the accessing user can see them.

Create or modify a submission specified by p, a submission ID.

Setting p=new will create a new submission; the response will contain the chosen submission ID.

The modification may be specified:

1. As a JSON request body (when the request body has content-type application/json).
2. As a ZIP archive (when the request body has content-type application/zip). The archive must contain a file named data.json; it may contain other files too.
3. As a JSON-formatted request parameter named json (when the request body has content-type application/x-www-form-urlencoded or multipart/form-data).
4. As a previously-uploaded JSON or ZIP file, represented by a upload token in the upload parameter.

In all of these, the modification is defined by a JSON submission object. The properties of this object define the modifications applied to the submission. The object need not specify all submission properties; absent properties remain unchanged.

The p request parameter is optional. If it is unset, HotCRP uses the pid from the supplied JSON. If both the p parameter and the JSON pid property are present, however, then they must match.

To test a modification, supply a dry_run=1 parameter. This will test the uploaded JSON but make no changes to the database.

ZIP and form uploads

A ZIP upload should contain a file named data.json (PREFIX-data.json is also acceptable). This file’s content is parsed as JSON. Submission fields in the JSON can refer to other files in the ZIP. For instance, this shell session uploads a new submission with content paper.pdf:

$ cat data.json
{
    "object": "paper",
    "pid": "new",
    "title": "Aught: A Methodology for the Visualization of Scheme",
    "authors": [{"name": "Nevaeh Gomez", "email": "ngomez@example.edu"}],
    "submission": {"content_file": "paper.pdf"},
    "status": "submitted"
}
$ zip upload.zip data.json paper.pdf
$ curl -H "Authorization: bearer hct_XXX" --data-binary @upload.zip -H "Content-Type: application/zip" SITEURL/api/paper

This shell session does the same, but using multipart/form-data.

$ curl -H "Authorization: bearer hct_XXX" -F "json=<data.json" -F paper.pdf=@paper.pdf SITEURL/api/paper

Responses

If the modification succeeds, the response’s paper property contains the modified submission object.

The change_list property is a list of names of the modified fields. New submissions have "pid" as the first item in the list. change_list contains fields that the request attempted to modify; successful requests, erroneous requests, and dry-run requests can all return nonempty change_lists.

The valid property is true if and only if the modification was valid. In non-dry-run requests, valid: true indicates that database changes were committed.

Dry-run requests return change_list and valid properties, but not paper properties, since no modifications are performed.

Administrator use

Administrators can use this endpoint to set some submission properties, such as decision, that have other endpoints as well.

Administrators can choose specific IDs for new submissions; just set p (or JSON pid) to the chosen ID. Such a request will either modify an existing submission or create a new submission with that ID. To avoid overwriting an existing submission, set the JSON’s status.if_unmodified_since to 0.

Delete the submission specified by p, a submission ID.

Retrieve submission objects matching a search.

The search is specified in the q parameter; all matching visible papers are returned. Other search parameters (t, qt) are accepted too. The response property papers is an array of matching submission objects.

Since searches silently filter out non-viewable submissions, /papers?q=1010 and /paper?p=1010 can return different error messages. The /paper request might return an error like Submission #1010 does not exist or You aren’t allowed to view submission #1010, whereas the /papers request will return no errors. To obtain warnings for missing submissions that were explicitly listed in a query, supply a warn_missing=1 parameter.

Create or modify multiple submissions.

This administrator-only endpoint modifies multiple submissions at once. Its request formats are similar to that of POST /{p}/paper: it can accept a JSON, ZIP, or form-encoded request body with a json parameter, and ZIP and form-encoded requests can also include attached files.

The JSON provided for /papers should be an array of JSON objects. Response properties papers, change_lists, and valid are arrays with the same number of elements as the input JSON; component i of each response property contains the result for the ith submission object in the input JSON.

Alternately, you can provide a q search query parameter and a single JSON object. The JSON object must not have a pid property. The JSON modification will be applied to all papers returned by the q search query.

The response message_list contains messages relating to all modified submissions. To filter out the messages for a single submission, use the messages’ landmark properties. landmark is set to the integer index of the relevant submission in the input JSON.

Upload large files to HotCRP for later use.

Servers limit how much data they will accept in a single request. The upload API uploads larger files over multiple requests. When an upload is complete, later requests can refer to that file using an upload token.

The lifecycle of an upload is as follows.

1. A request with start=1 begins a new upload. This request should also include a size parameter to define the size of the uploaded file, if that is known.
2. The response to this request will include the upload token for the uploaded file in its token field. This is a string like hcupwhvGDVmHNYyDKdqeqA. All subsequent requests relating to the upload must include this token as a token parameter.
3. Subsequent requests upload the contents of the file in chunks. The blob parameter (which can be an attached file) contains the chunk itself; the offset parameter defines the offset of chunk relative to the file.
4. A request with finish=1 completes the upload. The server seals the upload and responds with the file’s content hash. A finish=1 request will fail unless all expected chunks have been received.

start=1 and finish=1 requests can also include a chunk. The ranges response field represents the ranges of bytes received so far.

The upload API is only available on sites that have enabled the document store.

Return IDs of submissions that match a search.

Pass the search query in the q parameter. The list of matching IDs is returned in the ids response property.

The t, qt, reviewer, sort, and scoresort parameters can also affect the search. t defines the collection of submissions to search. t=viewable checks all submissions the user can view; the default collection is often narrower (a typical default is t=s, which searches complete submissions).

The groups response property is an array of annotations that apply to the search, and is returned for THEN searches, LEGEND searches, and searches on tags with annotations. Each annotation contains a position pos, and may also have a legend, a search, an annoid, and other properties. pos is an integer index into the ids array; it ranges from 0 to the number of items in that array. Annotations with a given pos should appear before the paper at that index in the ids array. For instance, this response might be returned for the search 10-12 THEN 15-18:

{
    "ok": true,
    "message_list": [],
    "ids": [10, 12, 18],
    "groups": [
        {
            "pos": 0,
            "legend": "10-12",
            "search": "10-12"
        },
        {
            "pos": 2,
            "legend": "15-18",
            "search": "15-18"
        }
    ]
}