HotCRP Conference Review Software

Developers can interact with HotCRP via several interfaces:

• OpenAPI Specification: The API is defined in devel/openapi.json (or available at https://hotcrp.com/devel/api/).
• Hotcrapi: A command-line interface for accessing the HotCRP API.
• Development Manual: For advanced configuration, software internals, and extension development, refer to the HotCRP development manual.

When interacting with comment endpoints for a submission p, the c parameter selects the target comment. It accepts the following values:

• Numeric ID: A specific comment ID (e.g., 42).
• new: Creates a new ordinary comment (used with POST).
• response: Selects or creates the unnamed response.
• Named Response Selector: A specific response identifier like R2response (alternatively, set c=response and provide response=R2).

HotCRP provides specific endpoints to manage administrative assignments for a single submission (p). These include setting the decision, lead, shepherd, and manager.

Note for Integrations: These endpoints are thin wrappers around the general-purpose /assign machinery. If you are building an external integration that needs to update many submissions at once, you should use the /assign endpoint instead of these per-submission endpoints.

HotCRP supports three storage methods for document contents:

1. MySQL Database: The default method.
2. Docstore: Filesystem-based storage.
3. Amazon S3: Cloud-based storage.

Disabling Database Storage

If you have configured either a docstore or S3, you can disable storing document contents in the MySQL database to save space by setting: $Opt["dbNoPapers"] = true;

Using Docstore as an S3 Cache

If you configure both a docstore and S3, the docstore acts as a cache for S3. Incoming documents are stored in both locations. If a file is missing from the docstore, HotCRP will automatically attempt to retrieve it from S3.

A comment is returned as a JSON object with "object": "comment". It always includes a numeric cid (comment ID) and the pid (submission ID). Other fields depend on permissions and the content=false parameter:

• Placement: visibility, topic, and ordinal (e.g., A1, cA2).
• Content: text (body), format, tags, docs (attachments), and word_count. (Omitted if content=false is passed).
• Authorship: author, author_email, by_author (true if written by a submission author), by_shepherd, and pseudonym fields (author_pseudonym, author_pseudonymous, or author_hidden) for anonymized comments.
• State: draft (true if unsubmitted), blind, collapsed, response (round name), modified_at, and review_token.
• Permissions: editable, author_editable, and viewer_owned (true if the caller wrote it).

HotCRP provides a download=1 parameter for submission endpoints. When this parameter is set, the API returns the bare payload (the JSON object or an array of objects) as a file, rather than wrapping it in the standard HotCRP JSON envelope (which includes message_list, etc.).

This is useful for a download-edit-upload workflow:

1. Download: Use GET /api/{p}/paper?download=1 to get a single submission object, or GET /api/papers?download=1 to get an array.
2. Edit: Modify the JSON locally.
3. Upload: POST the resulting JSON back to /api/paper or /api/papers.

When interacting with review endpoints, the r parameter is used to select a specific review on submission p:

• Read endpoints (get /{p}/review, get /{p}/reviewhistory, get /{p}/reviewrating): Accept either a numeric review ID (e.g., 4) or a display ordinal (e.g., A).
• Lifecycle endpoints (post /acceptreview, post /declinereview, post /claimreview): Require a numeric review ID.
• Upload endpoint (post /review): Accepts new (for a freshly-created review) or an empty r (to target the caller's own review, creating it if necessary).

The meeting tracker coordinates live PC (Program Committee) meetings by broadcasting which submission is currently under discussion to all members' browsers. It walks through an ordered list of submissions (a "hotlist").

Key Concepts

• Tracker: Identified by a numeric trackerid. A tracker walks a specific list of submissions.
• Track Managers: Only chairs or PC members with administrative rights to a specific track can control trackers.
• Visibility: Trackers can be configured to be visible to the entire PC or only to members with a specific PC tag. They can also be configured to hide conflicted submissions.
• Concurrency: Multiple trackers can run simultaneously.

HotCRP sessions consist of two distinct layers of data stored using PHP's native session encoding:

1. Global session data: Data that applies to all conferences associated with the current session (e.g., user account information, security events, and recent IP addresses).
2. Conference session data: Data specific to a single conference, stored within an associative array keyed by the conference's session key (e.g., @db-sigcomm23).

This separation allows a single user session to maintain state across multiple different conferences while keeping conference-specific preferences (like display settings or score sorting) isolated.

An ftext (formatted text) is a string prefixed with its markup ID. This format is required by several HotCRP subsystems, such as error messages. The format is <MARKUPTYPE>STRING.

Common markup types used in ftexts are 0 (plain text) and 5 (HTML).

<0>Fortnum & Mason

API endpoints are restricted based on two distinct levels of administrative authority:

1. Site Administrator: Has site-wide authority over the entire conference (e.g., Chairs, sysadmins). Endpoints requiring this level are badged Site admin only.
2. Submission Administrator: Has authority over specific submissions or subsets (e.g., Track Managers, assigned PC members). Endpoints requiring this are badged Admin only or Track manager only.