Create Post

Upload and create a new post on Circlo

POST

Upload and create a new post on Circlo. The post can be an image or video.

Endpoint:

/api/user-preferences/recommend/create-post

Headers:

Authorization: Bearer YOUR_TOKEN_HERE
Content-Type: application/json

Request Body:

{
  "profile": "general" | "profile_id",
  "niche": "string",
  "media_type": "image" | "video",
  "media_source": "string (URL from Replicate)",
  "caption": "string (required)",
  "keywords": ["string"] (optional)
}

Request Body Fields:

profile - Either "general" or a specific profile ID. If "general", the post will be attached to a random profile with matching niche.
niche - The niche/sub-niche for the post. Required when profile is "general".
media_type - Type of media: "image" or "video"
media_source - Required. URL of the media from Replicate (image or video URL)
caption - Required. The caption text for the post
keywords - Optional array of keywords/hashtags

Example Request:

curl -X POST \
  https://api.getcirclo.com/api/user-preferences/recommend/create-post \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "profile": "general",
    "niche": "Tech Reviewer",
    "media_type": "image",
    "media_source": "https://replicate.delivery/pbxt/.../output.jpg",
    "caption": "Check out this amazing tech review!",
    "keywords": ["tech", "review", "gadgets"]
  }'

Example Response (201 Created):

{
  "success": true,
  "post": {
    "id": "uuid",
    "generatedProfileId": "uuid",
    "postType": "image",
    "caption": "Check out this amazing tech review!",
    "keywords": ["tech", "review", "gadgets"],
    "likeCount": 0,
    "commentCount": 0,
    "createdAt": "2025-11-05T02:20:00Z"
  }
}

Error Responses:

400: Bad Request - Missing required fields (media_source or caption)
404: Profile not found (when using specific profile ID)
500: Internal server error