Picnics API: Create and Manage Clody Community Channels

Bot authentication is accepted on read endpoints (GET /api/picnics/get, GET /api/picnics/overview, POST /api/picnic/get, POST /api/picnic/search, POST /api/picnic/comments, and the /@/<link> short-link resolver) via the Authorization: <user_id> <token> header.It is rejected on all lifecycle and moderation endpoints (create, edit, join, leave, delete, ban, unban, manage, set_original) — those return 400 Not Authorized when called with a bot token. A human owner must create the picnic and use manage to promote the bot to admin. See the Bots guide.

Picnics are Clody’s public community channels. Anyone can discover and join a picnic; once inside, admins post the content and members engage through comments. Every picnic has exactly one owner (its creator), one or more admins (including the owner), and any number of members. This page covers all endpoints for creating and managing picnics, as well as the real-time Socket.IO events your client receives as picnic state changes.

The Picnic object

The picnic_summary shape is returned by most endpoints on this page.

integer

Unique numeric identifier for the picnic.

string

Display name of the picnic (up to 30 characters).

string | null

URL of the picnic’s avatar image, or null if none has been set.

integer

Total number of current members.

string | null

Custom URL slug used in the short-link /@/<link>, or null if no custom link has been set.

object

Metadata object with the following nested fields:

Show data fields

string | null

Short description of the picnic (up to 50 characters), or null.

integer | null

ID of the currently pinned PMessage, or null if nothing is pinned.

boolean

true when the picnic has been marked as an official Clody original channel.

boolean

Whether comment threads are enabled for posts in this picnic.

boolean

true if the authenticated user is currently a member.

boolean

true if the authenticated user has admin privileges in this picnic.

boolean

true if the authenticated user is the owner of this picnic.

Endpoints

List your picnics

curl https://clody.example.com/api/picnics/get \
  -H "Cookie: session=<your_session>"

GET /api/picnics/get Returns the list of picnic IDs you currently belong to. Response 200

[1, 5, 42]

An array of integer picnic IDs. Returns an empty array [] if you have not joined any picnics.

Overview of your picnics

curl https://clody.example.com/api/picnics/overview \
  -H "Cookie: session=<your_session>"

GET /api/picnics/overview Returns full picnic summaries for every picnic you belong to, augmented with unread-post and last-activity metadata. Use this endpoint to populate a picnic sidebar or home screen. Response 200

[
  {
    "id": 1,
    "name": "Morning Crew",
    "avatar": "https://cdn.clody.example.com/avatars/1.png",
    "members_count": 318,
    "link": "morning-crew",
    "data": {
      "description": "Daily news and good vibes",
      "pinned": 99,
      "original": false
    },
    "supports_comments": true,
    "is_member": true,
    "is_admin": false,
    "is_owner": false,
    "unread": 4,
    "last_at": 1718000000
  }
]

integer

Number of posts in this picnic you have not yet read.

integer

Unix timestamp of the most recent post, or 0 if no posts exist yet.

Get a picnic

curl https://clody.example.com/api/picnic/get \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

POST /api/picnic/get Fetches the full summary for a single picnic by ID. You do not need to be a member to look up a picnic. Request body

integer

required

ID of the picnic to retrieve.

Response 200 — a Picnic object. Error responses

Status	Body	Meaning
`404`	`"Not Found"`	No picnic exists with that ID.

Search picnics

curl https://clody.example.com/api/picnic/search \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"name": "morning"}'

POST /api/picnic/search Searches all picnics by name using a case-insensitive substring match. Returns up to 50 results. Request body

string

required

Substring to search for in picnic names. Whitespace-only strings return an empty array immediately.

Response 200

[
  {
    "id": 1,
    "name": "Morning Crew",
    ...
  }
]

An array of up to 50 Picnic objects whose names contain the given substring.

Create a picnic

curl https://clody.example.com/api/picnic/create \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Morning Crew",
    "link": "morning-crew",
    "support_comments": true,
    "description": "Daily news and good vibes"
  }'

POST /api/picnic/create Creates a new picnic. You become the owner and are automatically added as the first admin and member. Request body

string

required

Display name for the picnic. Maximum 30 characters; cannot be blank.

boolean

required

Set to true to allow members to comment on posts, or false to disable comments entirely.

string

Custom URL slug (maximum 30 characters) used in the short-link /@/<link>. Must be globally unique. Omit or leave blank to skip assigning a custom link.

string

Short description shown on the picnic profile (maximum 50 characters).

Response 200 — the newly created Picnic object. Error responses

Status	Body	Meaning
`403`	`"Link is taken"`	Another picnic already uses that custom link.
`403`	`"You have 3 or more warns"`	Your account has 3 or more active warnings and cannot create picnics.

After a successful creation, all your connected sessions also receive an added_picnic Socket.IO event containing the new picnic summary.

Edit a picnic

curl https://clody.example.com/api/picnic/edit \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "name": "Morning Crew ☀️",
    "link": "morning-crew",
    "support_comments": true,
    "admins": [7, 12],
    "description": "Updated description"
  }'

POST /api/picnic/edit Updates a picnic’s settings. Only the owner can call this endpoint. The owner is always kept in the admins list regardless of what you pass. Request body

integer

required

ID of the picnic to edit.

string

required

New display name (maximum 30 characters).

boolean

required

Whether comment threads should be enabled on this picnic going forward.

array of integers

required

Complete list of member IDs to grant admin privileges. Non-members in this list are silently ignored. The owner is always prepended if not already present.

string | null

New custom URL slug (maximum 30 characters), or null to remove the existing link.

string | null

New description (maximum 50 characters), or null to clear it.

Response 200 — the updated Picnic object. Error responses

Status	Body	Meaning
`403`	`"Forbidden"`	You are not the owner of this picnic.
`403`	`"Link is taken"`	The requested link is already in use by another picnic.

Every current member receives an update_picnic Socket.IO event with their personalised picnic summary immediately after a successful edit.

Join a picnic

curl https://clody.example.com/api/picnic/join \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

POST /api/picnic/join Adds you as a member of the specified picnic. Request body

integer

required

ID of the picnic to join.

Response 200 — the Picnic object for the picnic you just joined. Error responses

Status	Body	Meaning
`403`	`"You are banned"`	You are banned from this picnic.
`403`	`"You are member"`	You are already a member.

Leave a picnic

curl https://clody.example.com/api/picnic/leave \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

POST /api/picnic/leave Removes you from the picnic’s member and admin lists. Request body

integer

required

ID of the picnic to leave.

Response 200 — "Success" Error responses

Status	Body	Meaning
`400`	`"You are owner"`	Owners cannot leave their own picnic. Transfer ownership or delete the picnic instead.

Delete a picnic

curl https://clody.example.com/api/picnic/delete \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

POST /api/picnic/delete Permanently deletes a picnic along with all its posts and comments. Only the owner can delete a picnic. This action is irreversible. Request body

integer

required

ID of the picnic to delete.

Response 200 — "Success" Error responses

Status	Body	Meaning
`403`	`"Forbidden"`	You are not the owner of this picnic.

Deleting a picnic removes all posts and comments permanently. Every current member receives a deleted_picnic Socket.IO event.

Manage a picnic

curl https://clody.example.com/api/picnic/manage \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"id": 1}'

POST /api/picnic/manage Returns the full membership roster for a picnic, including bans. Admins only. Request body

integer

required

ID of the picnic.

Response 200

{
  "members": [1, 7, 12, 99],
  "admins": [1, 7],
  "owner": 1,
  "bans": [55]
}

array of integers

IDs of all current members.

array of integers

IDs of all users with admin privileges (always includes the owner).

integer

User ID of the picnic owner.

array of integers

IDs of users who have been banned from this picnic.

Error responses

Status	Body	Meaning
`403`	`"Forbidden"`	You are not an admin of this picnic.

Ban a member

curl https://clody.example.com/api/picnic/ban \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"id": 1, "ban_id": 99}'

POST /api/picnic/ban Bans a user from a picnic. The banned user is removed from the member list and receives a banned_from_picnic Socket.IO event. Admins only. Request body

integer

required

ID of the picnic.

integer

required

User ID of the member to ban.

Response 200 — "Success" Error responses

Status	Body	Meaning
`403`	`"Forbidden"`	You are not an admin of this picnic.
`403`	`"Can't ban the owner"`	You cannot ban the picnic owner.
`403`	`"Remove role Admin"`	The target user is an admin; remove their admin role before banning.
`400`	`"Already banned"`	This user is already banned.

Unban a user

curl https://clody.example.com/api/picnic/unban \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"id": 1, "unban_id": 99}'

POST /api/picnic/unban Lifts a ban, allowing the user to rejoin the picnic. Admins only. Request body

integer

required

ID of the picnic.

integer

required

User ID of the banned user to unban.

Response 200 — "Success" Error responses

Status	Body	Meaning
`403`	`"Forbidden"`	You are not an admin of this picnic.
`404`	`"That is not banned"`	The specified user is not currently banned.

Short-link redirects

Every picnic with a custom link value is reachable at /@/<link>. Navigating to that URL redirects the browser to /app/picnics/<id> — the standard in-app picnic page. This lets you share a memorable URL (e.g. /@/morning-crew) instead of a numeric ID.

Route	Behaviour
`GET /@/<link>`	Redirects to `/app/picnics/<id>` for the picnic whose `link` matches. Returns `404` if no picnic has that link.

Custom links are set at creation time with the link field on POST /api/picnic/create, and can be updated or cleared via POST /api/picnic/edit.

Socket.IO events

Your client receives these events over the active Socket.IO connection when picnic state changes.

Event	Payload	When
`added_picnic`	Picnic object	You joined or created a picnic.
`update_picnic`	Picnic object	The picnic’s settings were changed (name, link, admins, comments toggle, pinned message, etc.).
`banned_from_picnic`	`{ "id": integer, "name": string }`	You were banned from a picnic.
`deleted_picnic`	`{ "id": integer }`	A picnic you belonged to was deleted.

Each update_picnic payload is personalised — is_member, is_admin, and is_owner reflect the receiving user’s relationship to the picnic, not the caller’s.

Auth & Users

Branches

Picnics

Interactions

Real-Time

Bots

Picnics API: Create and Manage Clody Community Channels

The Picnic object

Endpoints

List your picnics

Overview of your picnics

Get a picnic

Search picnics

Create a picnic

Edit a picnic

Join a picnic

Leave a picnic

Delete a picnic

Manage a picnic

Ban a member

Unban a user

Short-link redirects

Socket.IO events

​The Picnic object

​Endpoints

​List your picnics

​Overview of your picnics

​Get a picnic

​Search picnics

​Create a picnic

​Edit a picnic

​Join a picnic

​Leave a picnic

​Delete a picnic

​Manage a picnic

​Ban a member

​Unban a user

​Short-link redirects

​Socket.IO events

The Picnic object

Endpoints

List your picnics

Overview of your picnics

Get a picnic

Search picnics

Create a picnic

Edit a picnic

Join a picnic

Leave a picnic

Delete a picnic

Manage a picnic

Ban a member

Unban a user

Short-link redirects

Socket.IO events