Skip to main content
Bot is allowed — every endpoint on this page accepts bot authentication via the Authorization: <user_id> <token> header. See the Bots guide.
Clody uses an upload-then-reference pattern for all file attachments. You upload a file first and receive a filename back from the CDN. You then include that filename in the cdn array of a message creation request. Retrieval endpoints serve files back with membership checks so that only people who belong to the right Branch or Picnic can access the content.
You can attach up to 10 files per Branch message. Each upload endpoint enforces its own size limit — see the Limits table below.

​
Upload Endpoints

​
Upload a Branch file — POST /api/cdn/benches/upload

Uploads any file (image, video, document, etc.) to a Branch. You must be a member of the Branch to upload. Content-Type: multipart/form-data
​
binary
required
The file to upload. Maximum 30 MB.
​
string
required
Numeric ID of the Branch you are uploading to, passed as a form field string.
Response 200
​
string
Randomly generated filename (hex token + original extension). Use this value in your cdn array.
​
string
The original filename as provided by the client.
Error responses

​
Attach a GIF to a Branch — POST /api/cdn/benches/gif

Fetches a GIF from Giphy by URL and stores it in the Branch’s CDN directory. Use this after a successful POST /api/gifs/search to register the chosen GIF. Content-Type: application/json
​
integer
required
ID of the Branch.
​
string
required
A Giphy URL (hostname must be giphy.com or *.giphy.com). The server fetches the GIF server-side; you do not upload the binary yourself.
Response 200
Error responses
Only URLs from giphy.com or its subdomains (e.g. media2.giphy.com) are accepted. Passing any other URL returns 400 Bad Request.

​
Upload a Picnic file — POST /api/cdn/picnics/upload

Uploads a file to a Picnic’s CDN storage. Only Picnic admins can use this endpoint. Content-Type: multipart/form-data
​
binary
required
The file to upload. Maximum 30 MB.
​
string
required
Numeric ID of the Picnic, passed as a form field string.
Response 200
Error responses

​
Upload your user avatar — POST /api/cdn/avatars/upload

Replaces your user avatar. The server updates your profile immediately after a successful upload — no separate profile-update call is needed. Content-Type: multipart/form-data
​
binary
required
The image file. Maximum 30 MB.
Response 200
Error responses

​
Upload a Picnic avatar — POST /api/cdn/picnics/avatars/upload

Replaces the avatar for a Picnic community. Only the Picnic owner (not just an admin) can call this endpoint. On success the server immediately pushes an update_picnic Socket.IO event to all Picnic members. Content-Type: multipart/form-data
​
binary
required
The image file. Maximum 5 MB.
​
string
required
Numeric ID of the Picnic, passed as a form field string.
Response 200
Error responses

​
Retrieval Endpoints

​
Get a Branch file — GET /cdn/benches/<bench_id>/<filename>

Serves a file stored in a Branch. You must be a member of the Branch. Path parameters
​
integer
required
Numeric ID of the Branch.
​
string
required
The filename value returned by the upload endpoint.
Response 200 — raw file binary with the appropriate Content-Type. Error responses

​
Get a Picnic file — GET /cdn/picnics/<picnic_id>/<filename>

Serves a file stored in a Picnic. You must be authenticated to make this request. Path parameters
​
integer
required
Numeric ID of the Picnic.
​
string
required
The filename value returned by the upload endpoint.
Response 200 — raw file binary. Error responses

​
Get an avatar — GET /cdn/avatar/<filename>

Serves a user or Picnic avatar image. Any authenticated user can access any avatar by filename — there is no additional membership check. Path parameters
​
string
required
The filename value returned by one of the avatar upload endpoints.
Response 200 — image binary.

​
Limits

​
Example: Upload a File to a Branch

Response:
You can now include "3a1f8c2d4e5b607f9a0e1d2c3b4a5f67.pdf" in the cdn array of POST /api/bm/create.