HotCRP REST API (2025-10-18:8a0b6c22f)

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.

Delete the submission specified by p, a submission ID.

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 paper response property is 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.

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.

Fetch the share link for a submission, if any has been created. This link can be accessed by users not signed in to HotCRP; it grants view-only access to the submission and its documents. Only authors and administrators can fetch the share link.

Change the share link for a submission. The share parameter determines whether a link should be created; it must be one of:

no : Delete the current share link, if any.

yes : Update a share link or create one if necessary. The expiration time of a current share link may be extended if expires_in requests it.

reset : Reset the expiration time of an existing share link, if one exists.

new : Delete any existing share link and create a new one.

Only authors and administrators can modify a share link.

Delete the share link for a submission, if any has been created.

Fetch a document and return it in the response body. Specify the document to return either with the doc parameter, which names the document using a pattern like testconf-paper1.pdf, or the p, dt, and optionally attachment parameters, which define the submission ID, submission field, and attachment name.

The hash and docid parameters let administrators and authors select a specific version of a document. hash selects a document by hash, and docid by internal document ID. Responses to requests with hash or docid are usually cacheable.

Successful requests (HTTP status code 200) return the requested document as the response, without any JSON wrapper. Find the document’s MIME type using the response’s Content-Type header. Unsuccessful requests (HTTP status code 300 or higher) usually return a JSON object with ok set to false and a message_list describing the error.

This API understands conditional requests with HTTP headers If-Match, If-None-Match, If-Modified-Since, and If-Unmodified-Since, and many responses include ETag and Last-Modified HTTP headers. It also understands range requests.

Fetch information about all versions of a document accessible to the requesting user. Use the doc parameter to specify a document by name, or p and dt to specify it by type.

Run HotCRP’s PDF format checker on a specified document. A human-readable response is returned in message_list. The problem_fields response property lists the names of any PDF checks that failed; examples include "papersize", "pagelimit", "columns", "textblock", "bodyfontsize", "bodylineheight", and "wordlimit".

Fetch the contents of a ZIP, .tar, .tar.gz, .tar.bz2, or .tar.xz archive. The contents are returned as a list of string filenames. The consolidated=1 parameter requests an additional consolidated_listing, which returns a preformatted string that uses {} notation to represent subdirectories; for instance, subdir/{file1.txt, file2.txt}.

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

Display fields

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

f defines the display fields to return. An example is title authors[full]. Obtain the available display fields with the /displayfields API. format is either csv or html, and requests CSV or HTML format for the response data.

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

Return a list of all supported display fields. Display fields can be requested in the web UI (search for show:FIELDNAME) or in the API (supply f=FIELDNAME to the /search endpoint).