Posts
Managing posts via the Vibescaling API
List Posts
GET /api/v1/posts?status=draft&page=1&per_page=20Query Parameters
| Parameter | Type | Description |
|---|---|---|
| status | string | Filter by status: draft, scheduled, posted, archived |
| account_id | string | Filter by account UUID |
| page | number | Page number (default: 1) |
| per_page | number | Items per page (default: 20, max: 100) |
Response
{
"data": [...],
"pagination": {
"page": 1,
"per_page": 20,
"total": 42,
"total_pages": 3
}
}Create a Post
POST /api/v1/postsRequest body
{
"title": "My Post Title",
"caption": "Check out these slides!",
"hashtags": "#tiktok #content",
"hook": "Wait for it...",
"hook_type": "curiosity",
"angle_type": "educational"
}All fields except title are optional. Posts are created with status draft.
Get a Post
GET /api/v1/posts/:idUpdate a Post
PATCH /api/v1/posts/:idRequest body
Any combination of:
{
"title": "Updated title",
"caption": "New caption",
"hashtags": "#updated",
"status": "scheduled",
"scheduled_at": "2026-03-15T14:00:00Z",
"tiktok_account_id": "uuid"
}Scheduling via PATCH
Set status to scheduled along with scheduled_at and tiktok_account_id to schedule a post.
Archive a Post
DELETE /api/v1/posts/:idSets the post status to archived. This is a soft delete.
Upload Slides
POST /api/v1/posts/:id/assetsRequest body
{
"filename": "slide1.png",
"content_type": "image/png"
}Response
{
"upload_url": "https://...",
"r2_key": "orgs/{org}/posts/{post}/slides/slide1.png"
}Upload the file directly to upload_url via PUT request with the correct Content-Type header.
Post Object
| Field | Type | Description |
|---|---|---|
| id | uuid | Post ID |
| org_id | uuid | Organization ID |
| title | string | Post title |
| caption | string? | Post caption |
| hashtags | string? | Hashtags |
| hook | string? | Opening hook |
| status | string | draft, scheduled, posted, archived |
| scheduled_at | timestamp? | When the post is scheduled to publish |
| posted_at | timestamp? | When the post was published |
| tiktok_account_id | uuid? | TikTok account for publishing |
| created_at | timestamp | Creation time |
| updated_at | timestamp | Last update time |