Picnic Messages API: Post and Manage Channel Content

Bot is allowed — every endpoint on this page accepts bot authentication via the Authorization: <user_id> <token> header. A bot that has been promoted to admin can create, edit, and delete posts just like any human admin. See the Bots guide.

Picnic Messages (PMessages) are the posts that appear inside a Clody Picnic channel. Only picnic admins can create, edit, or delete posts — all members can read them. Posts support rich text content, CDN-hosted file attachments, read tracking, and a single pinned post per channel. Because authorship is hidden from regular members, admins have a dedicated endpoint to look up the real author of any post.

The PMessage object

integer

Unique numeric identifier for the post.

integer

ID of the picnic this post belongs to.

integer | null

User ID of the post author. Always null for regular members; admins see the real ID. Use POST /api/pm/get_author to fetch the author ID directly.

string

Text body of the post (up to 5 000 characters).

array of strings

List of CDN URLs for attached files or images. Up to 10 attachments per post.

boolean

true if the post has been edited after its original creation.

integer

Unix timestamp (seconds) when the post was created.

integer

Total number of members who have marked this post as read.

boolean

true if the authenticated user has already marked this post as read.

object

Reserved metadata object. Currently always {}.

Endpoints

List posts in a picnic

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

POST /api/pm/list Returns a paginated list of posts for a picnic, ordered from oldest to newest within the page. Use before_id to load earlier pages. Request body

integer

required

ID of the picnic whose posts you want to retrieve.

integer

Return only posts with an ID less than this value. Use the smallest ID from the previous page to paginate backwards in time.

integer

Number of posts to return. Defaults to 30; maximum 100.

Response 200

{
  "messages": [
    {
      "id": 101,
      "picnic": 1,
      "author": null,
      "content": "Good morning everyone! ☀️",
      "cdn": [],
      "edited": false,
      "created_at": 1718000000,
      "views": 42,
      "read_by_me": true,
      "data": {}
    }
  ],
  "has_more": true
}

array

Array of PMessage objects, in ascending chronological order.

boolean

true when older posts are available. Paginate by passing the lowest id from the current page as before_id.

The author field in each post is automatically null for regular members and populated with the real user ID for admins — no extra call needed when listing.

Get a single post

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

POST /api/pm/get Fetches a single post by its ID. Request body

integer

required

ID of the post to retrieve.

Response 200 — a PMessage object. Error responses

Status	Body	Meaning
`404`	`"Not Found"`	No post (or picnic) exists with that ID.

Get post author (admins only)

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

POST /api/pm/get_author Returns the real user ID of the author of a post. Admins only. Regular members always see null for the author field; use this endpoint when you need the explicit author ID. Request body

integer

required

ID of the post whose author you want to identify.

Response 200

An integer representing the author’s user ID. Error responses

Status	Body	Meaning
`403`	`"Forbidden"`	You are not an admin of the picnic this post belongs to.
`404`	`"Not Found"`	No post (or picnic) exists with that ID.

Create a post (admins only)

curl https://clody.example.com/api/pm/create \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{
    "picnic": 1,
    "content": "Today'\''s update is live 🎉",
    "cdn": ["https://cdn.clody.example.com/files/abc123.png"]
  }'

POST /api/pm/create Publishes a new post to a picnic. Admins only. Request body

integer

required

ID of the picnic to post in.

string

required

Text body of the post (maximum 5 000 characters).

array of strings

Up to 10 CDN URLs for file or image attachments. Defaults to an empty array if omitted.

Response 200 — the newly created PMessage object (with author visible since you are an admin). Error responses

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

Every member of the picnic (including you) receives a new_pmessage Socket.IO event after a successful create. Admins receive the event with author populated; regular members receive it with author set to null.

Edit a post (admins only)

curl https://clody.example.com/api/pm/edit \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"id": 101, "content": "Corrected content here"}'

POST /api/pm/edit Updates the text content of an existing post and marks it as edited. Admins only. CDN attachments cannot be changed after creation. Request body

integer

required

ID of the post to edit.

string

required

New text body (maximum 5 000 characters).

Response 200 — the updated PMessage object. Error responses

Status	Body	Meaning
`403`	`"Forbidden"`	You are not an admin of this picnic.
`404`	`"Not Found"`	No post (or picnic) exists with that ID.

Every member receives an update_pmessage Socket.IO event after a successful edit.

Delete a post

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

POST /api/pm/delete Permanently deletes a post and all its associated comments. You can delete a post if you are a picnic admin or the original author of that post. Request body

integer

required

ID of the post to delete.

Response 200 — "Success" Error responses

Status	Body	Meaning
`403`	`"Forbidden"`	You are neither an admin nor the author of this post.
`404`	`"Not Found"`	No post (or picnic) exists with that ID.

Deleting a post also permanently removes all comments on that post. Every member receives a delete_pmessage Socket.IO event.

Mark a post as read

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

POST /api/pm/mark_read Records that you have read a post. This increments the post’s views count and sets read_by_me to true in subsequent fetches. Calling this endpoint on a post you’ve already read is a no-op. Request body

integer

required

ID of the post to mark as read.

Response 200 — "Success" Error responses

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

Pin or unpin a post (admins only)

# Pin a post
curl https://clody.example.com/api/pm/pin_message \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"id": 101, "pin": true}'

# Unpin the current post
curl https://clody.example.com/api/pm/pin_message \
  -X POST \
  -H "Cookie: session=<your_session>" \
  -H "Content-Type: application/json" \
  -d '{"id": 101, "pin": false}'

POST /api/pm/pin_message Pins or unpins a post for the whole picnic. Each picnic can have at most one pinned post at a time. Pinning a new post automatically replaces the previous pin. Admins only. The pinned post ID is reflected in data.pinned on the Picnic object. Request body

integer

required

ID of the post to pin or unpin.

boolean

required

true to pin the post, false to unpin it.

Response 200 — "Success" Error responses

Status	Body	Meaning
`403`	`"Forbidden"`	You are not an admin of this picnic.
`404`	`"Not Found"`	No post (or picnic) exists with that ID.

After a successful pin/unpin, every member receives an update_picnic Socket.IO event reflecting the updated data.pinned value.

Socket.IO events

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

Event	Payload	When
`new_pmessage`	PMessage object	A new post is published in a picnic you belong to.
`update_pmessage`	PMessage object	An existing post is edited.
`delete_pmessage`	`{ "id": integer, "picnic_id": integer }`	A post is deleted. Remove it from your local state using the `id` field.

For all three events, the author field in the payload is personalised: admins receive the real author ID while regular members receive null.

Auth & Users

Branches

Picnics

Interactions

Real-Time

Bots

Picnic Messages API: Post and Manage Channel Content

The PMessage object

Endpoints

List posts in a picnic

Get a single post

Get post author (admins only)

Create a post (admins only)

Edit a post (admins only)

Delete a post

Mark a post as read

Pin or unpin a post (admins only)

Socket.IO events

​The PMessage object

​Endpoints

​List posts in a picnic

​Get a single post

​Get post author (admins only)

​Create a post (admins only)

​Edit a post (admins only)

​Delete a post

​Mark a post as read

​Pin or unpin a post (admins only)

​Socket.IO events

The PMessage object

Endpoints

List posts in a picnic

Get a single post

Get post author (admins only)

Create a post (admins only)

Edit a post (admins only)

Delete a post

Mark a post as read

Pin or unpin a post (admins only)

Socket.IO events