HotCRP REST API (2025-08-26:1d75c73ed)

Fetch a submission object specified by p, a submission ID. The submission object is returned in the paper response property. Error messages—for instance, about permission errors or nonexistent submissions—are returned in message_list.

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, 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

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

The change_list response property lists any modified field names. 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 response returns the modified submission object paper property contains the modified submission object.

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 by setting 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 submission JSON’s status.if_unmodified_since to 0.

Delete the submission specified by p, a submission ID.

Fetch submission objects matching a search.

The search is specified in the q parameter (and other search parameters, such as t and qt). All matching visible submissions are returned, as an array of submission objects, in the response property papers.

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.

Modify submissions independently

The JSON provided for /papers should be an array of JSON objects. The status_list response property is an array with the same number of elements as the input JSON. Component i of status_list reports the status of update i as an object with valid, change_list, and pid properties; these report the validity of the update, the list of changed fields, and the submission ID of the modified submission.

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.

Modify all matching submissions

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

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.

Perform assignments, specified either as a JSON array or as an uploaded CSV file.

The assignments should be compatible with HotCRP’s bulk assignments format. They may be specified:

1. As a JSON request body (when the request body has content-type application/json).
2. As a CSV file (when the request body has content-type text/csv).
3. As a JSON-formatted request parameter named assignments (when the request body has content-type application/x-www-form-urlencoded or multipart/form-data).
4. As a previously-uploaded JSON or CSV file, represented by a upload token in the upload parameter.

JSON requests should parse to arrays of objects. Each object should contain at least a pid property and an action property, where action determines what kind of assignment to run. Similarly, CSV uploads should contain at least pid and action columns.

If the optional p request parameter is set, HotCRP will only implement assignments that affect that submission.

To test an assignment, supply a dry_run=1 parameter. This will parse the uploaded assignment and report any errors, but make no changes to the database.

The valid response property is true if and only if the assignments were valid (had no errors). In non-dry-run requests, "valid": true indicates that any database changes were committed.

The response includes an assignments property, which is an array of the specific assignments performed (or, for dry-run requests, the specific assignments that would be performed). Each entry in assignments represents a single action applied to a single submission. (This differs from input assignments entries, each of which might apply to many submissions specified by a search.) If you’re not interested in the assignments property, supply a parameter of either summary=1 (to get summary assignment_actions and assignment_pids properties) or quiet=1 (to get nothing).

Return IDs, and optionally other display fields, of submissions that match a search.

Pass the search query in the q parameter. The list of matching submission IDs is returned in the ids response property, ordered according to the search.

The t, qt, reviewer, sort, and scoresort parameters can also affect the search. t defines the collection of submissions to search, where t=viewable checks all submissions the user can view. If t is not provided, HotCRP picks a default based on the user’s roles and the site’s current configuration; for PC members and chairs, the typical default is t=s, which searches complete submissions.

Submission fields

Pass f and format parameters to retrieve display fields for each submission in the search result.

format is either csv or html, and requests CSV or HTML format for the response data. f is a string indicating the display fields to return, such as title authors[full].

The response will contain fields and papers properties. fields is an array of objects defining the emitted display fields. Typically, each entry in fields corresponds to a member of f, but some field requests can expand into multiple display fields. papers is an array of objects defining the exported fields for each matching submission. Each papers entry has a pid property with the submission ID, and properties corresponding to the fields. The papers entries are in the same order as ids. In some cases, the response will additionally have a statistics property defining overall statistics for some of the requested fields.

As an example, this response might be returned for the search 10-12 with format=csv and f=title.

{
    "ok": true,
    "ids": [10, 12],
    "fields": [
        {
            "name": "title",
            "title": "Title",
            "order": 120,
            "sort": "ascending"
        }
    ],
    "groups": [],
    "papers": [
        {
            "pid": 10,
            "title": "Active Bridging"
        },
        {
            "pid": 12,
            "title": "Dynamics of Random Early Detection"
        }
    ]
}

Please note that html format is unlikely to be useful outside the HotCRP web application. The returned HTML uses elements, tag structures, and class names suitable for HotCRP’s internal use, and may change at any time. Furthermore, in some cases (such as f=allpref), the returned data is compressed into a field-specific format that the HotCRP web application expands.

Search annotations

The groups response property is an array of search annotations, and is returned for THEN searches, LEGEND searches, and searches on annotated tags. Each groups entry contains a position pos, which is an integer index into the search results. Annotations with pos P should appear immediately before the submission at index P in the result. A groups entry may also have other properties, including legend (the textual legend corresponding to the annotation), search (for THEN searches, the search string representing the following results), and annoid.

As an example, this response might be returned for the search 10-12 THEN 5-8.

{
    "ok": true,
    "ids": [10, 12, 8],
    "groups": [
        {
            "pos": 0,
            "legend": "10-12",
            "search": "10-12"
        },
        {
            "pos": 2,
            "legend": "5-8",
            "search": "5-8"
        }
    ]
}

More

The search_params response property is a URL-encoded string defining all relevant parameters for the search.

Set the hotlist parameter to get a hotlist response property, which is used by the HotCRP browser Javascript to remember information about a list of papers.

Return a list of search actions accessible via HotCRP’s API.

Search actions perform actions on a set of papers specified via search. In the HotCRP web application, search actions are shown underneath the search list; examples include “Download > Review forms (zip)” and “Tag > Add to order”. The /searchactions API endpoint retrieves the search actions that the current user can access programmatically via the /searchaction API.

Perform the search action specified by the action parameter on the papers defined by the q and t search parameters.

The action parameter must correspond to the name of a valid search action, as returned from the /searchactions API endpoint. Other parameters may be provided; the /searchactions response mentions relevant parameters for each action.

Search action responses do not follow HotCRP’s typical conventions. Successful responses may not use the JSON content type. For instance, the get/paper action typically returns a ZIP file containing submission PDFs, and the get/csv action returns a CSV-formatted text file. Furthermore, successful JSON responses may not be objects, or may not contain an ok property; for example, a successful response to a get/json request is an array of objects. Applications wanting predictable JSON responses should use other API endpoints. Nevertheless, /searchaction can be more convenient than using more standardized APIs.

Perform the search action specified by the action parameter on the papers defined by the q and t search parameters.

The request format for POST requests is the same as for GET requests.