milian/docs/Google文档完整内容-0.6.12.txt

Registration API

API Version
0.6.12

Status
Deployed to production and verified through the public API (Jenkins build 46, 2026-10-21).

Production Base URL
https://melove.youthome.com.cn

All URLs below use the production HTTPS server. Do not add /api/v1 twice. Replace {user_id}, {target_user_id}, {post_id}, and {media_id} with numeric IDs returned by the API.

1. Register a User

URL
POST https://melove.youthome.com.cn/api/v1/auth/register

Authentication
Not required.

Request Header
Content-Type: application/json

Request JSON
{
  "email_or_phone": "user@example.com",
  "password": "password123",
  "confirm_password": "password123",
  "relationship_goal": "serious_relationship"
}

email_or_phone accepts either an email address or a phone number.

Optional profile fields may be included:
{
  "email_or_phone": "user@example.com",
  "password": "password123",
  "confirm_password": "password123",
  "relationship_goal": "serious_relationship",
  "full_name": "Test User",
  "gender": "female",
  "birth_date": "2000-01-01",
  "city": "Shanghai",
  "country": "China",
  "bio": "I like traveling.",
  "interests": ["Photography", "Movies"]
}

Required fields are email_or_phone, password, confirm_password, and relationship_goal. relationship_goal must be one of serious_relationship, casual_dates, new_friends, or marriage.

Do not include the profile image or introduction video in this JSON. Upload them separately after registration using the access token.

Backend Response (201 Created)
{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "token_type": "bearer"
}

The registration response contains tokens only, not the complete user profile. Save both tokens, then call GET /api/v1/auth/me.

Rules
- Password length: 8 to 128 characters.
- confirm_password must match password and is not stored.
- If interests is supplied, at least two non-empty interests are required. Custom interests are allowed; there is no maximum number.
- The account becomes active immediately after registration.
- This MVP does not require OTP or verification-code requests.

Possible Errors
- 409: email or phone number is already registered.
- 422: a required field is missing or invalid, passwords do not match, or interests are invalid.

2. Upload or Replace the Profile Image

URL
POST https://melove.youthome.com.cn/api/v1/users/me/image

Authentication
Authorization: Bearer <access_token>

Request Format
multipart/form-data

File field name: image

Supported formats: JPG, PNG, WebP. Maximum size: 10 MB.

A successful upload replaces the previous profile image. The response contains the new media ID, media type, and review status.

To display the current image, call GET /api/v1/auth/me and use profile.profile_image_url. In production this is a directly loadable, temporary signed URL valid for one hour; it is not a permanent fixed link and does not need another Bearer header. Request the profile again after it expires.

3. Upload or Replace the Introduction Video

URL
POST https://melove.youthome.com.cn/api/v1/users/me/video

Authentication
Authorization: Bearer <access_token>

Request Format
multipart/form-data

File field name: video

Supported formats: MP4, MOV, WebM. Maximum size: 100 MB.

A successful upload replaces the previous introduction video and removes the current written biography. Use profile.video_url from GET /api/v1/auth/me to display it. The production URL is a temporary signed URL. Saving a non-empty bio later through the profile-update API removes the introduction video.

4. Get the Current User

URL
GET https://melove.youthome.com.cn/api/v1/auth/me

The compatibility URL GET https://melove.youthome.com.cn/api/v1/users/me returns the same response.

Authentication
Authorization: Bearer <access_token>

Request Body
None.

Backend Response (200 OK)
The response contains the current user, nested profile, recent posts, recent liked users, recent users who liked the current user, recent matches, and the full totals liked_users_count, liked_by_users_count, and matches_count.

{
  "id": 28,
  "email_or_phone": "user@example.com",
  "status": "active",
  "profile": {
    "full_name": "User Name",
    "gender": "female",
    "birth_date": "2000-09-04",
    "city": "Shanghai",
    "county": "Huangpu",
    "country": "China",
    "relationship_goal": "serious_relationship",
    "bio": null,
    "occupation": null,
    "education": null,
    "height_cm": null,
    "beliefs": null,
    "smoking": null,
    "drinking": null,
    "pets": null,
    "exercise": null,
    "age": 26,
    "profile_image_url": "<temporary signed image URL or null>",
    "video_url": "<temporary signed video URL or null>",
    "interests": ["Movies", "Travel"]
  },
  "created_at": "2026-09-28T10:00:00",
  "posts": [],
  "liked_users": [],
  "liked_by_users": [],
  "matches": [],
  "liked_users_count": 0,
  "liked_by_users_count": 0,
  "matches_count": 0
}

The four activity arrays contain up to 20 recent items each. The three count fields are complete totals and are not limited to those 20 items. Likes include both like and super_like, and only active users are counted. profile_image_url and video_url are temporary signed media URLs in production; call this endpoint again after expiry.

5. Update the Current User's Profile

URL
PATCH https://melove.youthome.com.cn/api/v1/users/me

Authentication
Authorization: Bearer <access_token>

Request Header
Content-Type: application/json

Example Request
{
  "full_name": "New Name",
  "gender": "female",
  "birth_date": "2000-01-01",
  "city": "Shanghai",
  "country": "China",
  "relationship_goal": "marriage",
  "bio": "Updated biography",
  "occupation": "Creative Director at Studio Drift",
  "education": "NYU Gallatin School",
  "height_cm": 175,
  "beliefs": "spiritual_agnostic",
  "smoking": "non_smoker",
  "drinking": "socially",
  "pets": "golden_retriever",
  "exercise": "active_4x_week",
  "interests": ["Travel", "Music"]
}

Only send fields that need to change. Saving a non-empty bio removes the introduction video. Changing city through this endpoint clears the old county; use the location endpoint to submit coordinates, city, and county together. Interests are replaced as a whole and must contain at least two values when supplied.

Additional optional profile fields: occupation and education (max 120 characters each), height_cm (integer, 100-250), beliefs (max 120), smoking and drinking (max 50 each), pets (max 120), and exercise (max 50). Send null to clear any of them. GET /api/v1/auth/me returns these values plus a computed age derived from birth_date.

Backend Response (200 OK)
Returns the updated user information.

6. Update the Current User's Location

URL
PUT https://melove.youthome.com.cn/api/v1/users/me/location

Authentication
Authorization: Bearer <access_token>

Request JSON
{
  "latitude": 31.2304,
  "longitude": 121.4737,
  "city": "Shanghai",
  "county": "Huangpu"
}

All four fields are required. Latitude must be between -90 and 90; longitude must be between -180 and 180; city and county cannot be blank. county means district or county and is separate from country.

Backend Response (200 OK)
{
  "latitude": 31.2304,
  "longitude": 121.4737,
  "city": "Shanghai",
  "county": "Huangpu",
  "updated_at": "2026-10-09T10:00:00"
}

After updating the location, call GET /api/v1/auth/me to see profile.city and profile.county. Invalid fields return 422.

7. Refresh an Expired Access Token

URL
POST https://melove.youthome.com.cn/api/v1/auth/refresh

Authentication
Bearer access token is not required.

Request JSON
{
  "refresh_token": "<refresh_token>"
}

On success, the server returns a new access token and refresh token. Save both new tokens; the old refresh token becomes invalid. If refreshing returns 401, the user must log in again.

Explore / News Feed API

8. Get Recommended People (Meet)

URL
GET https://melove.youthome.com.cn/api/v1/meet?limit=20

Authentication
Authorization: Bearer <access_token>

limit is optional, defaults to 20, and can be from 1 to 50. The response contains active users whom the current user has not already swiped. Active incoming Super Likes have first priority. The remaining users are ordered by same city, same country, and then other countries; higher compatibility_percentage comes first within each group. Use the returned numeric id as target_user_id in the swipe API.

profile_image_url, video_url, and media[] describe public profile media, not posts. Production media URLs are temporary signed URLs valid for one hour.

9. Swipe Left, Swipe Right, or Super Like

URL
POST https://melove.youthome.com.cn/api/v1/meet/swipes

Authentication
Authorization: Bearer <access_token>

Request JSON
{
  "target_user_id": 28,
  "direction": "like"
}

target_user_id is the numeric ID returned by Meet or Search. Supported directions:

- pass: swipe left and skip the person.
- like: swipe right and like the person.
- super_like: like the person and give the sender first priority in that person's Meet list.

Backend Response (200 OK)

Without a mutual match:
{"direction": "like", "matched": false, "match_id": null}

With a mutual match:
{"direction": "like", "matched": true, "match_id": 15}

A match forms only when both users positively swipe each other. super_like counts as a positive swipe. Its priority remains until the sender cancels it or changes the direction. A pass removes an existing match.

9.1 Get Matches

URL
GET https://melove.youthome.com.cn/api/v1/matches

The compatibility URL GET https://melove.youthome.com.cn/api/v1/users/me/matches returns the same data.

Authentication
Authorization: Bearer <access_token>

Request Body
None. This endpoint does not paginate. Legacy limit and offset query parameters are ignored.

Backend Response (200 OK)
An array of MatchResponse. Each item contains id, matched_at, and the other user's public profile in user.

Rules
- Only matches whose other user is active are returned, most recent match first.
- An empty array means the current user has no active matches.
- A match is created only when both users positively swipe each other (like or super_like).
- pass, canceling a like, or undoing a swipe removes the corresponding match.
- The number of items equals matches_count from GET /api/v1/auth/me.

9.2 Get Users I Liked and Users Who Liked Me

URL
GET https://melove.youthome.com.cn/api/v1/users/me/liked
GET https://melove.youthome.com.cn/api/v1/users/me/likes

Authentication
Authorization: Bearer <access_token>

Request Body
None. These endpoints do not paginate. Legacy limit and offset query parameters are ignored.

Backend Response (200 OK)
An array of DiscoveryUserResponse.

Rules
- /users/me/liked returns users the current user liked with like or super_like.
- /users/me/likes returns users who liked the current user.
- Users who already matched with the current user are excluded from both lists.
- liked_users_count and liked_by_users_count in GET /api/v1/auth/me also exclude matched users.
- Only active users are returned, most recent action first.

10. Undo a Swipe (Cancel Button)

URL
DELETE https://melove.youthome.com.cn/api/v1/meet/swipes/{target_user_id}

Authentication
Authorization: Bearer <access_token>

No JSON body is needed. This is the URL for the frontend Cancel button. It removes the current user's saved pass, like, or super_like toward the target. The target may appear in Meet again. Canceling a Super Like removes its priority. If the swipe created a match, cancellation removes that match.

Backend Response (200 OK)
{
  "message": "已撤销滑动",
  "previous_direction": "super_like"
}

previous_direction may be pass, like, or super_like. If there is no saved swipe, the server returns 404. Cancel does not send another left or right swipe.

11. Cancel a Like (Older Compatibility URL)

URL
DELETE https://melove.youthome.com.cn/api/v1/meet/likes/{target_user_id}

This older compatibility URL cancels only like or super_like and removes any corresponding match. It cannot undo a pass. The new frontend Cancel button should use the Undo a Swipe URL above.

12. Search People

URL
GET https://melove.youthome.com.cn/api/v1/search

Authentication
Authorization: Bearer <access_token>

All query parameters are optional.

Parameters
- q: free-text keyword, maximum 200 characters. Fuzzy search on full_name, bio, city, and country, case-insensitive. Multiple words are AND-ed.
- city: exact city filter, case and whitespace insensitive.
- country: exact country filter, case and whitespace insensitive.
- latitude and longitude: must be sent together. They are used to compute distance_km and to sort by distance.
- max_distance_km: distance filter from 1 to 500. If it is sent without coordinates, the backend uses the current user's own location; the user must have set a location first, otherwise the API returns 422.
- limit: number of results, 1 to 50, default 20.

Filter examples
GET https://melove.youthome.com.cn/api/v1/search?q=hiking&limit=20
GET https://melove.youthome.com.cn/api/v1/search?city=Shanghai&limit=20
GET https://melove.youthome.com.cn/api/v1/search?country=China&limit=20
GET https://melove.youthome.com.cn/api/v1/search?city=Shanghai&country=China&limit=20
GET https://melove.youthome.com.cn/api/v1/search?latitude=31.2304&longitude=121.4737&max_distance_km=20&limit=20

Rules
- Only active users are returned, and the current user is excluded.
- q is a fuzzy contains match; city and country are exact equality matches.
- Sending only one of latitude or longitude returns 422.
- The backend first selects up to 500 candidates, then sorts and returns at most limit results.
- With coordinates, results are ordered by: users who sent the current user an active super_like first, then same city, same country, other countries; within each group by compatibility_percentage descending, then distance ascending, then newest user first.
- Without coordinates, the same group ordering is used without the distance step.

Backend Response (200 OK)
An array of public user profiles. Each item contains:
id, full_name, gender, birth_date, city, county, country, relationship_goal, bio, profile_image_url, video_url, distance_km, compatibility_percentage, media.

distance_km is null when coordinates were not provided. The result id can be used in the public-profile URL or the swipe URL. county is the district or county and is not the country filter.

13. Get the Explore / News Feed

URL
GET https://melove.youthome.com.cn/api/v1/explore/feed?limit=20&offset=0

Authentication
Authorization: Bearer <access_token>

limit controls the number of posts and accepts 1-50. offset loads later pages: use offset=0 for the first page, offset=20 for the second page, and so on. The optional legacy before_id is a numeric ID cutoff and cannot be combined with a non-zero offset; omit it completely when using offset pagination.

Backend Response (200 OK)
[
  {
    "id": 21,
    "content": "Today is a beautiful day.",
    "post_type": "text",
    "content_format": "plain",
    "feeling": null,
    "location": null,
    "author": {
      "id": 2,
      "full_name": "Bob",
      "profile_image_url": "<temporary signed avatar URL or null>",
      "city": "Shanghai",
      "country": "China",
      "compatibility_percentage": 85
    },
    "like_count": 2,
    "comment_count": 0,
    "liked_by_me": false,
    "liked_by_users": [
      {"id": 3, "full_name": "Newest Liker"},
      {"id": 4, "full_name": "Reader"}
    ],
    "media": [],
    "created_at": "2026-09-01T10:00:00"
  }
]

This URL returns posts, not user profiles. Posts by same-city authors come first, followed by same-country authors and then others; compatibility and recency also affect the order. liked_by_users contains only active users, newest like first, and only exposes ID and name. It is [] without likes and like_count equals its length. author.profile_image_url is null before upload or a temporary signed URL in production.

14. Get a Public User Profile

URL
GET https://melove.youthome.com.cn/api/v1/users/{user_id}

Authentication
Authorization: Bearer <access_token>

Use this URL when opening a person from Meet or Search. The response contains that person's public profile, including city, county, country, relationship goal, profile_image_url, video_url, public media, interests, and the newest 20 public posts. profile_image_url is the avatar and video_url is the introduction video. Profile media[] is not a list of posts. This endpoint never returns email/phone, account status, private likes, or matches.

15. List a Public User's Posts

URL
GET https://melove.youthome.com.cn/api/v1/users/{user_id}/posts?limit=20&offset=0

Authentication
Authorization: Bearer <access_token>

Replace user_id with a numeric ID. limit is 1 to 50, default 20; offset defaults to 0 and loads later pages. The response is an array of that user's posts, newest first. Each post includes content_format, feeling, location, an author with profile_image_url, liked_by_users, and its own post media[]. An empty array means the user has no posts.

16. Create a Post

URL
POST https://melove.youthome.com.cn/api/v1/explore/posts

Authentication
Authorization: Bearer <access_token>

Request Header
Content-Type: application/json

Request JSON
{
  "content": "Feeling happy and relaxed today",
  "post_type": "text",
  "content_format": "plain",
  "feeling": "happy",
  "location": {
    "name": "Blue Bottle Coffee, Soho NYC",
    "latitude": 40.723,
    "longitude": -73.998
  }
}

post_type can be text, image, or video; the default is text. Content has a maximum of 5,000 characters. A text post must contain at least one of non-empty content, feeling, or location. feeling is optional and contains 1 to 50 characters. If location is provided, name is required; latitude and longitude must be supplied together or both omitted. content_format can be plain or markdown; use markdown for bold and italic text. Music is not supported yet.

Backend Response (201 Created)
Returns a PostResponse with id, content, post_type, content_format, feeling, location, author, like_count, comment_count, liked_by_me, liked_by_users, media[], and created_at. For an image or video post, create the post first and use its returned ID in the next API. media[] is empty before upload.

16.1 Edit a Post

URL
PATCH https://melove.youthome.com.cn/api/v1/explore/posts/{post_id}

Authentication
Authorization: Bearer <access_token>

Only the post author can edit the post.

Request Header
Content-Type: application/json

Request JSON (send only the fields to change)
{
  "content": "Updated text",
  "content_format": "markdown",
  "feeling": "happy",
  "location": {"name": "New place"}
}

Editable fields: content (maximum 5,000 characters), content_format (plain or markdown), feeling (1 to 50 characters), and location. Omitted fields stay unchanged. Sending null clears feeling or location. A text post must keep at least one of non-empty content, feeling, or location.

Backend Response (200 OK)
Returns the full updated PostResponse.

Errors
- 403: the caller is not the post author.
- 404: the post does not exist or the author is inactive.
- 422: invalid fields, or the text post would be empty.

17. Upload Media to a Post

URL
POST https://melove.youthome.com.cn/api/v1/explore/posts/{post_id}/media?position=0

Authentication
Authorization: Bearer <access_token>

Only the post author can upload media.

Request Format
multipart/form-data

File field name: media

Optional query parameter: position from 0 to 9.

A post supports up to 9 images and 1 video in the same post. Images and video can be mixed.

- Images: JPG, PNG, or WebP; up to 10 MB each; maximum 9.
- Video: MP4, MOV, or WebM; up to 100 MB; maximum 1.

When the post contains both an image and a video, post_type becomes mixed. When it contains only one type, post_type is image or video.

Backend Response (201 Created)
Returns id, media_type, mime_type, size_bytes, position, and url. Fetch the post or feed again to obtain its updated media[]. Production media URLs are temporary signed URLs valid for one hour.

Errors
- 403: the caller is not the post author.
- 404: the post does not exist.
- 409: more than 9 images or more than 1 video.
- 413: the file is too large.
- 415: unsupported file type.

18. Post Likes and Comments

Every post response includes liked_by_users, an array of active post likers containing only id and full_name, ordered newest first. The same fields are used in Explore, post detail, public-user posts, and profile-embedded posts. Every comment author includes profile_image_url; use it to display the comment author's avatar.

Like a Post

URL
POST https://melove.youthome.com.cn/api/v1/explore/posts/{post_id}/like

Authentication
Authorization: Bearer <access_token>

Request Body
None.

Backend Response (200 OK)
{
  "message": "like successful",
  "like_count": 1,
  "liked_by_me": true,
  "liked_by_users": [{"id": 2, "full_name": "Reader"}]
}

The response is compact and does not contain the full post body, author, or media. Repeated likes are idempotent; update the existing post with the returned count, state, and list.

Get Post Likers

URL
GET https://melove.youthome.com.cn/api/v1/explore/posts/{post_id}/like

Authentication
Authorization: Bearer <access_token>

Request Body
None. No pagination parameters.

Backend Response (200 OK)
[{"id": 2, "full_name": "Reader"}]

Returns [] if there are no active likes. Only active users appear, newest like first.

Unlike a Post

URL
DELETE https://melove.youthome.com.cn/api/v1/explore/posts/{post_id}/like

Authentication
Authorization: Bearer <access_token>

Request Body
None.

Backend Response (200 OK)
{
  "message": "unlike successful",
  "like_count": 0,
  "liked_by_me": false,
  "liked_by_users": []
}

The response is compact and does not contain the full post. Repeated requests keep the post unliked.

Get or Add Comments

URL
GET https://melove.youthome.com.cn/api/v1/explore/posts/{post_id}/comments
POST https://melove.youthome.com.cn/api/v1/explore/posts/{post_id}/comments

Authentication
Authorization: Bearer <access_token>

POST Request JSON
{"content": "Nice post!"}

To reply to an existing comment, add parent_comment_id:
{"content": "I agree", "parent_comment_id": 12}

GET returns a flat CommentResponse array (200). POST returns the created CommentResponse (201). Content must be 1 to 2,000 characters and cannot be blank. Each comment contains author.profile_image_url (null when no avatar exists), parent_comment_id, reply_count, like_count, and liked_by_me. Group replies by parent_comment_id on the frontend.

Edit a Comment

URL
PATCH https://melove.youthome.com.cn/api/v1/explore/comments/{comment_id}

Authentication
Authorization: Bearer <access_token>

Only the comment author can edit the comment.

Request JSON
{"content": "Updated comment"}

Content must be 1 to 2,000 characters and cannot be blank.

Backend Response (200 OK)
Returns the updated CommentResponse.

Errors
- 403: the caller is not the comment author.
- 404: the comment does not exist.
- 422: invalid content.

Delete a Comment

URL
DELETE https://melove.youthome.com.cn/api/v1/explore/comments/{comment_id}

Authentication
Authorization: Bearer <access_token>

Only the comment author can delete the comment.

Backend Response (200 OK)
{"message": "评论已删除"}

Errors
- 403: the caller is not the comment author.
- 404: the comment does not exist.

Like a Comment

URL
POST https://melove.youthome.com.cn/api/v1/explore/comments/{comment_id}/like

Authentication
Authorization: Bearer <access_token>

Request Body
None.

Backend Response (200 OK)
{"message": "like successful", "like_count": 1, "liked_by_me": true}

Repeated likes do not increase the count.

Unlike a Comment

URL
DELETE https://melove.youthome.com.cn/api/v1/explore/comments/{comment_id}/like

Authentication
Authorization: Bearer <access_token>

Request Body
None.

Backend Response (200 OK)
{"message": "unlike successful", "like_count": 0, "liked_by_me": false}

19. Chat

Chat is available only between two users who have already matched. A conversation cannot be created before the match exists.

How to get match_id:
- POST https://melove.youthome.com.cn/api/v1/meet/swipes returns matched and match_id when the other person had already positively swiped you.
- GET https://melove.youthome.com.cn/api/v1/matches lists all match records with their IDs.

19.1 Create or Get a Conversation

URL
POST https://melove.youthome.com.cn/api/v1/chat/conversations/{match_id}

Authentication
Bearer token required. The caller must be one of the two users in that match.

Request Body
None. The match_id is taken from the URL path. There is no other parameter.

Backend Response (201 Created)
{
  "id": 12,
  "match_id": 34,
  "other_user": {
    "id": 55,
    "full_name": "Alex",
    "city": "Shanghai",
    "country": "China"
  },
  "last_message": null,
  "created_at": "2026-10-16T02:10:24",
  "updated_at": "2026-10-16T02:10:24"
}

Rules
- match_id must be a match the caller belongs to. Use the match_id returned by the swipe API or by GET /api/v1/matches.
- POST https://melove.youthome.com.cn/api/v1/chat/conversations (without match_id) is not supported. That URL only accepts GET. A POST there returns 405.
- Calling this URL again for the same match returns the same conversation; no duplicate conversation is created.
- last_message is null until a message has been sent.
- Errors: 404 when the match does not exist, when the caller is not one of the matched users, or when the other user is no longer active.

19.2 Get the Conversation List

URL
GET https://melove.youthome.com.cn/api/v1/chat/conversations

Authentication
Bearer token required.

Backend Response (200 OK)
[
  {
    "id": 12,
    "match_id": 34,
    "other_user": {
      "id": 55,
      "full_name": "Alex",
      "city": "Shanghai",
      "country": "China"
    },
    "last_message": {
      "id": 108,
      "conversation_id": 12,
      "sender_id": 55,
      "content": "Hello!",
      "message_type": "text",
      "is_deleted": false,
      "created_at": "2026-10-16T02:12:05"
    },
    "created_at": "2026-10-16T02:10:24",
    "updated_at": "2026-10-16T02:12:05"
  }
]

Rules
- The list contains one entry per match of the current user, most recent match first.
- A match whose other user is no longer active is skipped.
- id is null only when the match has no conversation yet; such an entry is returned so the client can still show the matched person.
- other_user currently contains id, full_name, city, and country. It does not contain an avatar URL yet.

19.3 Get Chat Messages

URL
GET https://melove.youthome.com.cn/api/v1/chat/conversations/{conversation_id}/messages?limit=50&before_id=100

Authentication
Bearer token required. The caller must be one of the conversation participants.

Parameters
- limit: 1 to 100, default 50.
- before_id: optional message ID used to load older messages; omit it for the newest page.

Backend Response (200 OK)
[
  {
    "id": 107,
    "conversation_id": 12,
    "sender_id": 54,
    "content": "Hi!",
    "message_type": "text",
    "is_deleted": false,
    "created_at": "2026-10-16T02:11:40"
  }
]

Rules
- Messages are returned in chronological order (oldest to newest) inside a page, even though before_id walks backwards in time.
- To load older messages, pass the smallest id from the current page as before_id.
- Errors: 404 conversation not found or access denied.

19.4 Send a Chat Message

URL
POST https://melove.youthome.com.cn/api/v1/chat/conversations/{conversation_id}/messages

Authentication
Bearer token required. The caller must be one of the conversation participants.

Request JSON
{
  "content": "Hello, nice to meet you!",
  "message_type": "text"
}

Backend Response (201 Created)
{
  "id": 108,
  "conversation_id": 12,
  "sender_id": 54,
  "content": "Hello, nice to meet you!",
  "message_type": "text",
  "is_deleted": false,
  "created_at": "2026-10-16T02:12:05"
}

Rules
- content: 1 to 5,000 characters after trimming; an empty content returns 422.
- message_type currently supports text only.
- Errors: 404 conversation not found, conversation belongs to someone else, or the other user is unavailable; 422 empty or malformed content.

19.5 Recall a Chat Message

URL
DELETE https://melove.youthome.com.cn/api/v1/chat/messages/{message_id}

Authentication
Bearer token required. Only the sender can recall their own message.

Backend Response (200 OK)
{
  "id": 108,
  "conversation_id": 12,
  "sender_id": 54,
  "content": null,
  "message_type": "text",
  "is_deleted": true,
  "created_at": "2026-10-16T02:12:05"
}

Rules
- After recall, content is null and is_deleted is true; the record is kept, not physically deleted.
- Errors: 403 the message was not sent by the caller; 404 message not found or the caller is not a participant of that conversation.

Chat message fields
id, conversation_id, sender_id, content, message_type, is_deleted, created_at.

Requirement Coverage

- Registration uses the production HTTPS URL and requires relationship_goal.
- OTP is not used in the MVP; registration activates the account immediately.
- JWT access and refresh tokens are used; passwords are hashed and never stored as plaintext.
- Profile images and introduction videos have separate upload URLs.
- Location updates submit latitude, longitude, city, and county together.
- Meet prioritizes users who sent an active Super Like.
- Swipe left uses pass; swipe right uses like; Super Like uses super_like.
- A match forms when both users positively swipe each other.
- The match list returns every active match without pagination.
- Users who already matched are removed from the liked and liked-by lists.
- Comments support replies (parent_comment_id) and likes.
- The Cancel Button undoes pass, like, or super_like using the swipe DELETE URL.
- Super Like priority remains until the sender cancels it or changes the direction.
- Search can filter by keyword, city, country, or distance.
- Explore returns posts; the public-user URL returns public profile information and recent public posts.
- Get Current User returns full liked_users_count, liked_by_users_count, and matches_count values.
- Create Post supports text, images, videos, feeling, location, and Markdown bold and italic. Music is not supported yet.
- Post media is uploaded after the post is created.
- Profile media and post media are different.
- Post and comment authors expose profile_image_url; post liker summaries expose ID and name.
- Profile editing supports occupation, education, height, beliefs, smoking, drinking, pets, and exercise; Get Me returns them with a computed age.
- Posts and comments can be edited by their authors.
- One post can contain up to 9 images and 1 video together.

How Each API Link Works

Production Base URL: https://melove.youthome.com.cn

For protected requests, send Authorization: Bearer <access_token>. Replace path IDs with real numeric IDs returned by earlier responses.

1. Register -> save both tokens -> Get Current User.
2. Optionally upload an avatar or introduction video -> Get Current User again.
3. Update Location -> Get Current User -> Get Meet recommendations.
4. Meet -> choose a returned user ID -> send pass, like, or super_like -> inspect matched and match_id.
5. Cancel Button -> DELETE the saved swipe -> refresh Meet and Matches.
6. Open a person's profile -> Get Public User Profile -> List that user's posts.
7. Create a post -> use its returned ID to upload images or video -> refresh Explore and profile posts.
8. Like a post -> use the compact response to update the existing post; call GET /like when the full liker list is needed.
9. Match -> take match_id from the swipe response or GET /api/v1/matches -> POST /api/v1/chat/conversations/{match_id} -> GET /api/v1/chat/conversations/{conversation_id}/messages -> POST the same messages URL to send a message.
10. To recall a message, DELETE /api/v1/chat/messages/{message_id} with the sender token.

Typical Frontend Order

Register -> save tokens -> Get Current User -> optionally upload avatar or introduction video -> Get Current User again.

Update Location -> Get Current User -> Get Meet recommendations.

Meet -> choose a returned user ID -> send pass, like, or super_like -> inspect matched and match_id.

Cancel Button -> DELETE the saved swipe -> refresh Meet and Matches.

Open a person's profile -> Get Public User Profile -> List that user's posts.

Create a post -> use the returned ID to upload images or video -> refresh Explore and profile posts.

Post like -> update count, state, and list from the compact response; do not replace the full post object with the like response.

Edit a post or comment -> PATCH the post or comment URL -> update the local item with the returned object.