Skip to main content

​
Overview

The Posts API provides endpoints for managing user-generated posts. Posts support text content, images, videos, and can be scoped to global, space, or group contexts.

​
List Posts

Retrieve a paginated list of posts with filtering and sorting options.

​
Request

curl -X GET "https://your-domain.com/api/posts?scope=global&page=1&perPage=30" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"
​
scope
string
Filter by scope: global, space, or group
​
space
string
Filter by space ID (when scope is space)
​
group
string
Filter by group ID (when scope is group)
​
q
string
Search query for post content
​
page
number
default:"1"
Page number for pagination
​
perPage
number
default:"30"
Number of posts per page
​
sort
string
default:"new"
Sort order: new (most recent) or top (most liked)

​
Response

{
  "items": [
    {
      "id": "RECORD_ID",
      "collectionId": "posts_collection_id",
      "collectionName": "posts",
      "created": "2026-03-01 12:00:00.000Z",
      "updated": "2026-03-01 12:00:00.000Z",
      "author": "USER_ID",
      "content": "This is a post",
      "scope": "global",
      "space": null,
      "group": null,
      "mediaType": "text",
      "attachments": [],
      "likeCount": 5,
      "commentCount": 3,
      "publishedAt": "2026-03-01 12:00:00.000Z"
    }
  ],
  "page": 1,
  "perPage": 30,
  "totalItems": 100,
  "totalPages": 4
}
​
items
array
Array of post objects
​
items[].id
string
Post ID
​
items[].author
string
User ID of post author
​
items[].content
string
Post content (max 2000 characters)
​
items[].scope
string
Post scope: global, space, or group
​
items[].mediaType
string
Media type: text, images, or video
​
items[].attachments
array
Array of attachment filenames
​
items[].likeCount
number
Number of likes on the post
​
items[].commentCount
number
Number of comments on the post

​
Get Post

Retrieve a single post by ID.

​
Request

curl -X GET "https://your-domain.com/api/posts/{id}" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Response

{
  "id": "RECORD_ID",
  "collectionId": "posts_collection_id",
  "collectionName": "posts",
  "created": "2026-03-01 12:00:00.000Z",
  "updated": "2026-03-01 12:00:00.000Z",
  "author": "USER_ID",
  "content": "This is a post",
  "scope": "global",
  "space": null,
  "group": null,
  "mediaType": "text",
  "attachments": [],
  "likeCount": 5,
  "commentCount": 3,
  "publishedAt": "2026-03-01 12:00:00.000Z"
}

​
Create Post

Create a new post with optional media attachments.

​
Request

curl -X POST "https://your-domain.com/api/posts" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -F "content=This is my new post" \
  -F "scope=global" \
  -F "mediaType=text"
​
content
string
required
Post content (max 2000 characters)
​
scope
string
default:"global"
Post scope: global, space, or group
​
space
string
Space ID (required when scope is space)
​
group
string
Group ID (required when scope is group)
​
mediaType
string
Media type: text, images, or video. Auto-detected from attachments if not provided.
​
attachments
file[]
Media files to attach (images or video)
​
mediaAltText
string
Alt text for media accessibility
​
videoPoster
file
Poster image for video posts
​
videoDuration
number
Video duration in seconds
​
publishedAt
string
Custom publish timestamp (ISO 8601 format)

​
Response

{
  "id": "RECORD_ID",
  "collectionId": "posts_collection_id",
  "collectionName": "posts",
  "created": "2026-03-01 12:00:00.000Z",
  "updated": "2026-03-01 12:00:00.000Z",
  "author": "USER_ID",
  "content": "This is my new post",
  "scope": "global",
  "space": null,
  "group": null,
  "mediaType": "text",
  "attachments": [],
  "likeCount": 0,
  "commentCount": 0,
  "publishedAt": "2026-03-01 12:00:00.000Z"
}

​
Update Post

Update an existing post. Users can only update their own posts.

​
Request

curl -X PUT "https://your-domain.com/api/posts/{id}" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated post content"
  }'
​
content
string
Updated post content

​
Response

{
  "id": "RECORD_ID",
  "collectionId": "posts_collection_id",
  "collectionName": "posts",
  "created": "2026-03-01 12:00:00.000Z",
  "updated": "2026-03-01 13:00:00.000Z",
  "author": "USER_ID",
  "content": "Updated post content",
  "scope": "global",
  "space": null,
  "group": null,
  "mediaType": "text",
  "attachments": [],
  "likeCount": 5,
  "commentCount": 3
}

​
Delete Post

Delete a post. Users can only delete their own posts.

​
Request

curl -X DELETE "https://your-domain.com/api/posts/{id}" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Response

{
  "success": true
}

​
Like Post

Toggle like status on a post (like if not liked, unlike if already liked).

​
Request

curl -X POST "https://your-domain.com/api/posts/{id}/like" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Response

{
  "liked": true,
  "likeCount": 6
}
​
liked
boolean
Whether the post is now liked by the current user
​
likeCount
number
Updated like count

​
Get Like Status

Check if the current user has liked a post.

​
Request

curl -X GET "https://your-domain.com/api/posts/{id}/like" \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN"

​
Response

{
  "liked": true,
  "likeCount": 6
}

​
Media Validation

Posts support the following media types:
  • Images: JPEG, PNG, WebP, GIF, HEIC, HEIF (max 5MB per file, up to 4 images)
  • Video: MP4 (max 50MB, single video per post)
The mediaType field is automatically inferred from attachments if not explicitly provided.

Build docs developers (and LLMs) love

Get started for freeTalk to us