REST routes

Most of the API is RPC, called with @hailer/cli. A few operations are plain HTTP routes instead - file and image downloads, uploads, insight exports, and calendar feeds. They live at versionless paths under the base URL (https://api.hailer.com) and are called with any HTTP client.

Authentication

Routes come in two forms:

• Authenticated - send the session key as the hlrkey cookie or header (the same session key described in Getting started).
• Public (/public/*) - no session required. The id or key in the path is the credential.

Files

GET /file/:id

Download a file by its fileId. Requires an authenticated session.

Parameter	In	Purpose
id	path	The file's fileId.
dl	query	If set, sent as an attachment (Content-Type: application/octet-stream) rather than inline.
downloadId	query	If set together with dl, a download.status signal is emitted to the user over Socket.IO as the download starts and finishes.

Responds with the file bytes. Inline responses use the file's own content type.

GET /public/file/:id

Same as above for files marked public - no session required.

POST /files

Download several files as a single zip archive. Requires an authenticated session.

• Body: JSON { "fileIds": ["<fileId>", ...], "archiveName": "<name>" }.
• Success: 200 with the archive bytes (Content-Type: application/zip), sent as an attachment named <archiveName>.zip.
• Errors: 403 if any of the files is not accessible to the session user.

POST /upload

Upload a file. Requires an authenticated session (hlrkey cookie, header, or body field), or a valid public-form key.

• Body: multipart/form-data with the file in a field named file.
• Success: 200 with { "_id": "<fileId>" }.
• Errors: 413 if the file exceeds the size limit; 401 if authentication fails.

Images

Images are served pre-rendered at named sizes.

GET /image/:size/:id

Render an image file at a given size. Requires an authenticated session.

Parameter	In	Purpose
size	path	One of the named sizes below.
id	path	The image file's fileId.
format	query	jpeg (default) or png.

Responds with the image bytes (Content-Type matching the requested format).

Sizes: square25, square50, square75, square100, square200, profile, smallface, bigface, thumb, gallerycover, fullhd, hires, lores, pdf, original.

GET /public/image/:size/:id

Same as above for public images - no session required.

GET /profileimage/:size/:id

A user's profile image at the given size (same size names as above). No session required.

Insight export

GET /public/insight/:id/:type?

Export a public insight's data. id is the insight's 32-character publicKey. No session required. See the Insights guide for details and the available query parameters (type, delimiter, separator, bom).

Calendar feed

GET /ical/:subscribe_code

Return an iCalendar feed of a calendar's events, for subscription in calendar apps. The subscribe_code in the path is the credential; no session is required.