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.

Workspace-scoped files. A file with a workspace (see the Files guide) is served only to its owner, admins and owners of that workspace, and users matched by its readers. Being able to see a message, post or activity the file is attached to grants nothing. Scoped files are never served over the /public/* routes or /profileimage/...; a denied request looks exactly like a missing file.

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. 404 when the file does not exist or the session user may not read it.

GET /public/file/:id

Same as above for files marked public - no session required. Workspace-scoped files always 404.

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 (including a workspace-scoped file they are not a reader of).

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, and optionally:
  • isPublic - "true" to serve the file over /public/file/:id.
  • workspaceId - scope the file to this workspace. The session user must be a member. A file scoped at upload has no readers: only its owner and the workspace's admins can read it until readers are granted with files.scope.set. Ignored on public-form uploads.
• Success: 200 with { "_id": "<fileId>" }.
• Errors: 400 if workspaceId is malformed or sent together with isPublic=true; 403 if the session user is not a member of workspaceId; 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). 404 when the image does not exist or the session user may not read it - the same rules as GET /file/:id.

Images of workspace-scoped files are sent with Cache-Control: private, no-cache and an ETag, so the browser revalidates them on every use: a matching If-None-Match gets 304 while the user can still read the file, and 404 once they cannot. Other images may be cached for a week (public, max-age=604800).

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. Workspace-scoped files always 404.

GET /profileimage/:size/:id

A user's profile image at the given size (same size names as above). No session required. Never serves a workspace-scoped file; the default profile picture is returned instead.

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.