Posts API — Profile Wall, Likes, and Image Uploads

Every Debuta user has a profile wall where they can share posts — text, an image, or both. These endpoints cover the full lifecycle of a post: creation (with optional Cloudinary image upload), fetching your own or another user’s timeline, toggling likes, and deletion. All five routes require a valid JWT in the Authorization header.

The Post Object

Every endpoint that returns a post (or array of posts) uses the following shape:

post

object

A single post document.

Show Post fields

_id

string

MongoDB ObjectId — unique identifier for the post.

text

string

Post body text. Maximum 500 characters. May be empty if the post is image-only.

image

object | null

Present when the post includes an uploaded image.

Show image fields

url

string

Public Cloudinary URL of the image.

public_id

string

Cloudinary public_id used internally for deletion.

author

object

Populated author snapshot.

Show author fields

first_name

string

Author’s first name.

last_name

string

Author’s last name.

username

string

Author’s unique handle.

profile_picture

object

Author’s profile picture (url, public_id).

is_verified

boolean

Whether the author has completed facial verification.

likes

string[]

Array of user ObjectIds who have liked the post. Use .length for the count.

createdAt

string

ISO 8601 timestamp of when the post was created.

updatedAt

string

ISO 8601 timestamp of the last update.

Endpoints

POST /api/posts

Create a new post with optional image upload.

GET /api/posts/me

Fetch the current user’s own posts.

GET /api/posts/user/:id

Fetch posts by another user’s ID.

POST /api/posts/:id/like

Toggle a like on a post.

DELETE /api/posts/:id

Delete a post you own.

POST /api/posts

Creates a new post. The request body must contain at least a non-empty text field or a photo attachment — sending neither returns 400. When a file is included, it is uploaded to Cloudinary before the post is saved. Authentication: Bearer JWT required. Content-Type: multipart/form-data (when attaching a file) or application/json (text-only).

Request body

text

string

required

The text content of the post. Maximum 500 characters. Required if no photo is supplied.

photo

file

Optional image file. Sent as a multipart field named photo. Accepted types: JPEG, PNG, WebP, HEIC. Maximum 10 MB. Uploaded to Cloudinary automatically.

Response `201`

{
  "message": "Publicación creada",
  "post": {
    "_id": "665f1a2b3c4d5e6f7a8b9c0d",
    "text": "Enjoying a perfect first date evening ✨",
    "image": {
      "url": "https://res.cloudinary.com/debuta/image/upload/v1/posts/abc123.jpg",
      "public_id": "posts/abc123"
    },
    "author": {
      "first_name": "Sofía",
      "last_name": "Ramírez",
      "username": "sofi.r",
      "profile_picture": {
        "url": "https://res.cloudinary.com/debuta/image/upload/v1/profiles/xyz.jpg",
        "public_id": "profiles/xyz"
      },
      "is_verified": true
    },
    "likes": [],
    "createdAt": "2024-06-04T18:30:00.000Z",
    "updatedAt": "2024-06-04T18:30:00.000Z"
  }
}

Error responses

Status	Condition
`400`	Neither `text` nor `photo` was provided.
`401`	Missing or invalid JWT.
`500`	Cloudinary upload failed or internal server error.

curl example

# Text-only post
curl -X POST https://api.debuta.app/api/posts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"text": "Enjoying a perfect first date evening ✨"}'

# Post with image
curl -X POST https://api.debuta.app/api/posts \
  -H "Authorization: Bearer <token>" \
  -F "text=Look at this amazing restaurant 🍷" \
  -F "photo=@/path/to/photo.jpg"

GET /api/posts/me

Returns a paginated list of posts created by the currently authenticated user, sorted newest first. Authentication: Bearer JWT required.

Query parameters

page

integer

default:"1"

Page number for pagination.

limit

integer

default:"20"

Number of posts per page. Maximum enforced by the client; server default is 20.

Response `200`

{
  "posts": [
    {
      "_id": "665f1a2b3c4d5e6f7a8b9c0d",
      "text": "My first post on Debuta!",
      "image": null,
      "author": {
        "first_name": "Sofía",
        "last_name": "Ramírez",
        "username": "sofi.r",
        "profile_picture": { "url": "...", "public_id": "..." },
        "is_verified": true
      },
      "likes": ["665f000000000000000000aa"],
      "createdAt": "2024-06-01T10:00:00.000Z",
      "updatedAt": "2024-06-01T10:00:00.000Z"
    }
  ]
}

curl example

curl -X GET "https://api.debuta.app/api/posts/me?page=1&limit=10" \
  -H "Authorization: Bearer <token>"

GET /api/posts/user/:id

Returns a paginated list of posts for any user by their MongoDB ObjectId. Used when viewing another user’s profile wall. Authentication: Bearer JWT required.

Path parameters

string

required

MongoDB ObjectId of the target user. Returns 400 if the ID format is invalid.

Query parameters

page

integer

default:"1"

Page number.

limit

integer

default:"20"

Posts per page.

Response `200`

{
  "posts": [
    {
      "_id": "665f1a2b3c4d5e6f7a8b9c0e",
      "text": "Incredible sunset tonight 🌅",
      "image": {
        "url": "https://res.cloudinary.com/debuta/image/upload/v1/posts/sunset.jpg",
        "public_id": "posts/sunset"
      },
      "author": {
        "first_name": "Carlos",
        "last_name": "Mendoza",
        "username": "carlos.m",
        "profile_picture": { "url": "...", "public_id": "..." },
        "is_verified": true
      },
      "likes": [],
      "createdAt": "2024-06-03T20:15:00.000Z",
      "updatedAt": "2024-06-03T20:15:00.000Z"
    }
  ]
}

Error responses

Status	Condition
`400`	`:id` is not a valid MongoDB ObjectId.
`401`	Missing or invalid JWT.

curl example

curl -X GET "https://api.debuta.app/api/posts/user/665f000000000000000000bb?page=1" \
  -H "Authorization: Bearer <token>"

POST /api/posts/:id/like

Toggles a like on a post. If the authenticated user has not previously liked the post their ID is added to the likes array; if they have already liked it, their ID is removed. This is idempotent — calling it twice returns the post to its original state. Authentication: Bearer JWT required.

Path parameters

string

required

MongoDB ObjectId of the post to like or unlike.

Response `200`

{
  "likes": 5,
  "liked": true
}

likes

number

Total number of likes on the post after the toggle.

liked

boolean

true if the current user’s action was a like; false if it was an unlike.

Error responses

Status	Condition
`404`	Post not found.
`401`	Missing or invalid JWT.

curl example

# Like (or unlike) a post
curl -X POST https://api.debuta.app/api/posts/665f1a2b3c4d5e6f7a8b9c0d/like \
  -H "Authorization: Bearer <token>"

DELETE /api/posts/:id

Permanently deletes a post. Only the post’s author can delete it — any other authenticated user receives 403. If the post has an attached Cloudinary image, it is also deleted from Cloudinary before the document is removed. Authentication: Bearer JWT required.

Path parameters

string

required

MongoDB ObjectId of the post to delete.

Response `200`

{
  "message": "Publicación eliminada"
}

Error responses

Status	Condition
`403`	Authenticated user is not the post author.
`404`	Post not found.
`401`	Missing or invalid JWT.

curl example

curl -X DELETE https://api.debuta.app/api/posts/665f1a2b3c4d5e6f7a8b9c0d \
  -H "Authorization: Bearer <token>"

Deletion is permanent and cannot be undone. The associated Cloudinary image is also removed as part of the same operation.

Authentication

Users & Profiles

Discovery & Matching

Chat & Calls

Content & Safety

Partners & Support

Posts API — Profile Wall, Likes, and Image Uploads

The Post Object

Endpoints

POST /api/posts

GET /api/posts/me

GET /api/posts/user/:id

POST /api/posts/:id/like

DELETE /api/posts/:id

POST /api/posts

Request body

Response `201`

Error responses

curl example

GET /api/posts/me

Query parameters

Response `200`

curl example

GET /api/posts/user/:id

Path parameters

Query parameters

Response `200`

Error responses

curl example

POST /api/posts/:id/like

Path parameters

Response `200`

Error responses

curl example

DELETE /api/posts/:id

Path parameters

Response `200`

Error responses

curl example

Build docs developers (and LLMs) love

Authentication

Users & Profiles

Discovery & Matching

Chat & Calls

Content & Safety

Partners & Support

Documentation Index

​The Post Object

​Endpoints

POST /api/posts

GET /api/posts/me

GET /api/posts/user/:id

POST /api/posts/:id/like

DELETE /api/posts/:id

​POST /api/posts

​Request body

​Response 201

​Error responses

​curl example

​GET /api/posts/me

​Query parameters

​Response 200

​curl example

​GET /api/posts/user/:id

​Path parameters

​Query parameters

​Response 200

​Error responses

​curl example

​POST /api/posts/:id/like

​Path parameters

​Response 200

​Error responses

​curl example

​DELETE /api/posts/:id

​Path parameters

​Response 200

​Error responses

​curl example

Build docs developers (and LLMs) love

The Post Object

Endpoints

POST /api/posts

Request body

Response `201`

Error responses

curl example

GET /api/posts/me

Query parameters

Response `200`

curl example

GET /api/posts/user/:id

Path parameters

Query parameters

Response `200`

Error responses

curl example

POST /api/posts/:id/like

Path parameters

Response `200`

Error responses

curl example

DELETE /api/posts/:id

Path parameters

Response `200`

Error responses

curl example