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.The Picnic object
Thepicnic_summary shape is returned by most endpoints on this page.
Custom URL slug used in the short-link
/@/<link>, or null if no custom link has been set.Endpoints
List your picnics
GET /api/picnics/get
Returns the list of picnic IDs you currently belong to.
Response 200
[] if you have not joined any picnics.
Overview of your picnics
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
Get a picnic
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
Response 200 — a Picnic object.
Error responses
Search picnics
POST /api/picnic/search
Searches all picnics by name using a case-insensitive substring match. Returns up to 50 results.
Request body
Substring to search for in picnic names. Whitespace-only strings return an empty array immediately.
200
Create a picnic
POST /api/picnic/create
Creates a new picnic. You become the owner and are automatically added as the first admin and member.
Request body
Set to
true to allow members to comment on posts, or false to disable comments entirely.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.200 — the newly created Picnic object.
Error responses
After a successful creation, all your connected sessions also receive an
added_picnic Socket.IO event containing the new picnic summary.Edit a picnic
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
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.
200 — the updated Picnic object.
Error responses
Every current member receives an
update_picnic Socket.IO event with their personalised picnic summary immediately after a successful edit.Join a picnic
POST /api/picnic/join
Adds you as a member of the specified picnic.
Request body
Response 200 — the Picnic object for the picnic you just joined.
Error responses
Leave a picnic
POST /api/picnic/leave
Removes you from the picnic’s member and admin lists.
Request body
Response 200 — "Success"
Error responses
Delete a picnic
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
Response 200 — "Success"
Error responses
Manage a picnic
POST /api/picnic/manage
Returns the full membership roster for a picnic, including bans. Admins only.
Request body
Response 200
Ban a member
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
Response 200 — "Success"
Error responses
Unban a user
POST /api/picnic/unban
Lifts a ban, allowing the user to rejoin the picnic. Admins only.
Request body
Response 200 — "Success"
Error responses
Short-link redirects
Every picnic with a customlink 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.