PRIMA API Documentation

Complete API documentation for the PRIMA Real Estate Platform microservices architecture.

Base URLs

Service	Base URL
Auth Service	`https://api.prima.com/auth/api/v1`
Authorization Service	`https://api.prima.com/authorization/api/v1`
Brok Service	`https://api.prima.com/brok/api/v1`
SNS Service	`https://api.prima.com/sns/api/v1`
File Processing Service	`https://api.prima.com/file-processing/api/v1`

Authentication

All protected endpoints require Bearer token authentication:

Authorization: Bearer {'{access_token}'}

Authentication

Send OTP

Send OTP to user's phone number for verification.

Endpoint: POST /auth/api/v1/send-otp

Request Parameters

Name	Type	Required	Description
phone_number	string	✅	User's phone number with country code

Request Example

{
  "phone_number": "+84389420092"
}

Response Example

{
  "success": true,
  "message": "OTP sent successfully",
  "data": {
    "CodeDeliveryDetails": {
      "Destination": "+84***092",
      "DeliveryMedium": "SMS"
    }
  }
}

Status Codes

200 - OTP sent successfully
404 - User not found
429 - Rate limit exceeded
500 - Internal server error

Verify OTP

Verify OTP code to confirm user registration.

Endpoint: POST /auth/api/v1/verify-otp

Request Parameters

Name	Type	Required	Description
phone_number	string	✅	User's phone number
otp	string	✅	6-digit verification code

Request Example

{
  "phone_number": "+84389420092",
  "otp": "123456"
}

Response Example

{
  "success": true,
  "message": "OTP verified successfully",
  "data": {
    "message": "Account verified successfully"
  }
}

Status Codes

200 - OTP verified successfully
400 - Invalid OTP or phone number
404 - User not found
500 - Internal server error

Register User

Endpoint: POST /auth/api/v1/register

Request Parameters

Name	Type	Required	Description
username	string	✅	Unique username
password	string	✅	User password (min 8 chars)
phone_number	string	✅	Phone number with country code
given_name	string	✅	User's first name
family_name	string	✅	User's last name

Request Example

{
  "username": "john_doe",
  "password": "SecurePass123!",
  "phone_number": "+84389420092",
  "given_name": "John",
  "family_name": "Doe"
}

Response Example

{
  "success": true,
  "message": "User registered successfully",
  "data": {
    "UserSub": "496a651c-6061-704e-3884-d420f8cfb352",
    "CodeDeliveryDetails": {
      "Destination": "+84***092",
      "DeliveryMedium": "SMS"
    }
  }
}

Status Codes

201 - User registered successfully
400 - Invalid input data or duplicate user
429 - Rate limit exceeded
500 - Internal server error

Authenticate user and return access tokens.

Endpoint: POST /auth/api/v1/login

Request Parameters

Name	Type	Required	Description
phone_number	string	✅	User's phone number
password	string	✅	User's password

Request Example

{
  "phone_number": "+84389420092",
  "password": "SecurePass123!"
}

Response Example

{
  "success": true,
  "message": "Login successful",
  "data": {
    "AccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "RefreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "ExpiresIn": 3600,
    "TokenType": "Bearer",
    "user": {
      "sub": "496a651c-6061-704e-3884-d420f8cfb352",
      "username": "john_doe",
      "phone_number": "+84389420092",
      "name": "John Doe",
      "role": "end_user"
    }
  }
}

Status Codes

200 - Authentication successful
400 - Invalid credentials
429 - Rate limit exceeded
500 - Internal server error

Refresh Token

Generate new access token using refresh token.

Endpoint: POST /auth/api/v1/refresh-token

Headers

Name	Type	Required	Description
X-User-Username	string	✅	User's username
X-Session-Id	string	✅	Session ID

Request Parameters

Name	Type	Required	Description
refresh_token	string	✅	Refresh token from login

Request Example

{
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Example

{
  "success": true,
  "message": "Token refreshed successfully",
  "data": {
    "AccessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "ExpiresIn": 3600,
    "TokenType": "Bearer"
  }
}

Status Codes

200 - Token refreshed successfully
401 - Invalid refresh token
500 - Internal server error

User Logout

Log out user by invalidating access token.

Endpoint: POST /auth/api/v1/logout

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}
X-User-Username	string	✅	User's username
X-Session-Id	string	✅	Session ID

Response Example

{
  "success": true,
  "message": "Logout successful",
  "data": {
    "message": "Successfully logged out"
  }
}

Status Codes

200 - Logout successful
401 - Invalid token
500 - Internal server error

Forgot Password

Initiate forgot password process by sending verification code.

Endpoint: POST /auth/api/v1/forgot-password

Request Parameters

Name	Type	Required	Description
phone_number	string	✅	User's phone number

Request Example

{
  "phone_number": "+84389420092"
}

Response Example

{
  "success": true,
  "message": "Verification code sent",
  "data": {
    "CodeDeliveryDetails": {
      "Destination": "+84***092",
      "DeliveryMedium": "SMS"
    }
  }
}

Status Codes

200 - Verification code sent successfully
404 - User not found
429 - Rate limit exceeded
500 - Internal server error

Confirm Forgot Password

Confirm forgot password with verification code and set new password.

Endpoint: POST /auth/api/v1/confirm-forgot-password

Request Parameters

Name	Type	Required	Description
phone_number	string	✅	User's phone number
confirmation_code	string	✅	Verification code received
new_password	string	✅	New password to set

Request Example

{
  "phone_number": "+84389420092",
  "confirmation_code": "123456",
  "new_password": "NewSecurePass123!"
}

Response Example

{
  "success": true,
  "message": "Password reset successfully",
  "data": {
    "message": "Password has been reset successfully"
  }
}

Status Codes

200 - Password reset successful
400 - Invalid verification code or password
404 - User not found
500 - Internal server error

User Management

Get Current User

Get current authenticated user's information.

Endpoint: GET /auth/api/v1/user/me

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}

Response Example

{
  "success": true,
  "message": "User information retrieved",
  "data": {
    "sub": "496a651c-6061-704e-3884-d420f8cfb352",
    "username": "john_doe",
    "phone_number": "+84389420092",
    "email": "john@example.com",
    "given_name": "John",
    "family_name": "Doe",
    "picture": "https://d37k5wtx5jh88r.cloudfront.net/avatar.jpg",
    "role": "end_user",
    "email_verified": true,
    "phone_number_verified": true
  }
}

Status Codes

200 - User information retrieved successfully
401 - Invalid or expired token
500 - Internal server error

Update Current User

Update current user's profile information.

Endpoint: PUT /auth/api/v1/user/me

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}

Request Parameters

Name	Type	Required	Description
given_name	string	❌	Updated first name
family_name	string	❌	Updated last name
email	string	❌	Updated email address

Request Example

{
  "given_name": "John Updated",
  "family_name": "Doe Smith",
  "email": "john.updated@example.com"
}

Response Example

{
  "success": true,
  "message": "User updated successfully",
  "data": {
    "message": "User attributes updated successfully"
  }
}

Status Codes

200 - User updated successfully
400 - Invalid input data
401 - Unauthorized
500 - Internal server error

Update Avatar

Update user's profile avatar image.

Endpoint: PUT /auth/api/v1/user/avatar

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}
x-user-id	string	✅	User's ID
x-user-username	string	✅	User's username

Request Parameters

Name	Type	Required	Description
avatar	file	✅	Image file (jpeg, png, bmp, webp)

Response Example

{
  "success": true,
  "message": "Avatar updated successfully",
  "data": {
    "picture": "https://d37k5wtx5jh88r.cloudfront.net/user/avatar.jpg"
  }
}

Status Codes

200 - Avatar updated successfully
400 - Invalid image type or size
401 - Unauthorized
500 - Avatar upload failed

Change Password

Change user's password.

Endpoint: POST /auth/api/v1/user/change_password

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}

Request Parameters

Name	Type	Required	Description
old_password	string	✅	Current password
new_password	string	✅	New password

Request Example

{
  "old_password": "CurrentPass123!",
  "new_password": "NewSecurePass456!"
}

Response Example

{
  "success": true,
  "message": "Password changed successfully",
  "data": {
    "message": "Password has been updated"
  }
}

Status Codes

200 - Password changed successfully
400 - Invalid old password or weak new password
401 - Unauthorized
429 - Rate limit exceeded
500 - Internal server error

Authorization

Get Permissions

Get all available permissions in the system.

Endpoint: GET /authorization/api/v1/permissions

Request Parameters

Name	Type	Required	Description
role_names	string	❌	Comma-separated role names to filter permissions

Response Example

{
  "success": true,
  "message": "Permissions retrieved successfully",
  "data": {
    "permission_names": [
      "create:user", "read:user", "update:user", "delete:user"
    ],
    "permissions": [
      {
        "_id": "64f0c8a9a0b8b0e6c8e3f4a1",
        "name": "create:user",
        "description": "Create new users",
        "is_active": true,
        "created_at": "2025-08-29T03:00:00.000Z"
      }
    ]
  }
}

Status Codes

200 - Permissions retrieved successfully
500 - Internal server error

Create Permission

Create a new permission.

Endpoint: POST /authorization/api/v1/permissions

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}

Request Parameters

Name	Type	Required	Description
name	string	✅	Unique permission name
description	string	✅	Permission description

Request Example

{
  "name": "manage:properties",
  "description": "Manage property listings"
}

Response Example

{
  "success": true,
  "message": "Permission created successfully",
  "data": {
    "_id": "64f0c8a9a0b8b0e6c8e3f4b1",
    "name": "manage:properties",
    "description": "Manage property listings",
    "is_active": true,
    "created_at": "2025-08-29T04:00:00.000Z"
  }
}

Status Codes

201 - Permission created successfully
400 - Invalid input or permission already exists
401 - Unauthorized
403 - Insufficient permissions
500 - Internal server error

Get Roles

Get all available roles in the system.

Endpoint: GET /authorization/api/v1/roles

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}

Response Example

{
  "success": true,
  "message": "Roles retrieved successfully",
  "data": {
    "items": [
      {
        "_id": "64f0c8a9a0b8b0e6c8e3f4a1",
        "name": "admin",
        "description": "System administrator",
        "permission_ids": ["perm1", "perm2"],
        "permission_names": ["create:user", "delete:user"],
        "is_active": true,
        "created_at": "2025-08-29T03:00:00.000Z"
      }
    ]
  }
}

Status Codes

200 - Roles retrieved successfully
401 - Unauthorized
403 - Insufficient permissions
500 - Internal server error

Create Role

Create a new role with specified permissions.

Endpoint: POST /authorization/api/v1/roles

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}

Request Parameters

Name	Type	Required	Description
name	string	✅	Unique role name
description	string	❌	Role description
permission_ids	array	✅	Array of permission IDs

Request Example

{
  "name": "property_manager",
  "description": "Manages property listings",
  "permission_ids": [
    "64f0c8a9a0b8b0e6c8e3f4a1",
    "64f0c8a9a0b8b0e6c8e3f4a2"
  ]
}

Response Example

{
  "success": true,
  "message": "Role created successfully",
  "data": {
    "_id": "64f0c8a9a0b8b0e6c8e3f4b1",
    "name": "property_manager",
    "description": "Manages property listings",
    "permission_ids": ["64f0c8a9a0b8b0e6c8e3f4a1"],
    "permission_names": ["manage:properties"],
    "is_active": true,
    "created_at": "2025-08-29T05:00:00.000Z"
  }
}

Status Codes

201 - Role created successfully
400 - Invalid input or role name already exists
401 - Unauthorized
403 - Insufficient permissions
500 - Internal server error

Property Content

Get Completed Videos

Get all completed videos with search capabilities for end users.

Endpoint: GET /brok/api/v1/completed

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}
x-language	string	❌	Language preference (en, vi, ko)

Request Parameters

Name	Type	Required	Description
page	number	❌	Page number (default: 1)
per_page	number	❌	Items per page (default: 10)
search	string	❌	Search term for properties
latitude	number	❌	Latitude for location filtering
longitude	number	❌	Longitude for location filtering
zoom_level	number	❌	Map zoom level for area filtering

Response Example

{
  "success": true,
  "message": "Videos retrieved successfully",
  "data": {
    "items": [
      {
        "id": "48c8c3b8-850d-48b9-97ce-ba353a075792",
        "price": 123313,
        "unit_price": "USD",
        "area": 12313,
        "unit_area": "ft²",
        "hash_tags": ["#DaNang", "#RealEstate", "#Vietnam"],
        "geo": {
          "type": "Point",
          "coordinates": [108.24668418789676, 16.028580442021536]
        },
        "profit_rate": {
          "roi": 72,
          "roa": 62
        },
        "amenities": ["internal_park", "parking_lot"],
        "video": {
          "size": 6403753,
          "original_name": "3773486-hd_1920_1080_30fps.mp4",
          "thumbnail_url": "https://d37k5wtx5jh88r.cloudfront.net/.../thumb.webp",
          "status": "completed",
          "content_url": "https://d37k5wtx5jh88r.cloudfront.net/.../video.mp4",
          "url": "https://d37k5wtx5jh88r.cloudfront.net/.../master.m3u8"
        },
        "real_estate_info": {
          "legal_certificates": "sale_contract",
          "apartment_type": "studio_apartment",
          "project_status": "pending"
        },
        "content_info": [
          {
            "lang": "en",
            "project_name": "Luxury Apartment",
            "description": "Modern apartment with sea view",
            "address": "282 Đ. Lê Văn Hiến, Khuê Mỹ, Ngũ Hành Sơn, Đà Nẵng",
            "location": "Đà Nẵng, Vietnam"
          }
        ],
        "uploader": {
          "user_id": "496a651c-6061-704e-3884-d420f8cfb352",
          "phone_number": "+84389420092",
          "name": "John Doe",
          "avatar": "https://d37k5wtx5jh88r.cloudfront.net/.../avatar.jpeg"
        },
        "images": [
          {
            "id": "969bf755-4bbc-4098-8e0a-fba203de8e40",
            "url": "https://d37k5wtx5jh88r.cloudfront.net/.../image1.png"
          }
        ],
        "reaction_count": 25,
        "created_at": "2025-08-29T07:04:29.454Z",
        "updated_at": "2025-08-29T09:15:57.627Z"
      }
    ],
    "total": 150,
    "page": 1,
    "per_page": 10,
    "total_pages": 15
  }
}

Status Codes

200 - Videos retrieved successfully
400 - Invalid query parameters
401 - Unauthorized
500 - Internal server error

Create Content

Create video content metadata.

Endpoint: POST /brok/api/v1/content

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}

Request Parameters

Name	Type	Required	Description
price	number	✅	Property price
unit_price	string	✅	Price unit
area	number	✅	Property area
unit_area	string	✅	Area unit
hash_tags	array	❌	Content hashtags
geo	object	❌	Geographic coordinates
amenities	array	❌	Property amenities
video	object	✅	Video information
real_estate_info	object	✅	Real estate details
content_info	array	✅	Multilingual content info
images	array	❌	Property images

Request Example

{
  "price": 150000,
  "unit_price": "USD",
  "area": 85,
  "unit_area": "m²",
  "hash_tags": ["#HoChiMinh", "#Apartment", "#LuxuryLiving"],
  "geo": {
    "type": "Point",
    "coordinates": [106.6297, 10.8231]
  },
  "amenities": ["swimming_pool", "gym", "parking"],
  "video": {
    "original_name": "property_tour.mp4",
    "size": 8500000
  },
  "real_estate_info": {
    "legal_certificates": "pink_book",
    "apartment_type": "luxury_apartment",
    "project_status": "completed"
  },
  "content_info": [
    {
      "lang": "en",
      "project_name": "Luxury Downtown Apartment",
      "description": "Modern luxury apartment in the heart of Ho Chi Minh City",
      "address": "123 Nguyen Hue Street, District 1, Ho Chi Minh City",
      "location": "Ho Chi Minh City, Vietnam"
    }
  ],
  "images": [
    {
      "url": "https://example.com/property1.jpg",
      "name": "Living Room"
    }
  ]
}

Response Example

{
  "success": true,
  "message": "Content created successfully",
  "data": {
    "id": "new-content-id-456",
    "price": 150000,
    "unit_price": "USD",
    "area": 85,
    "unit_area": "m²",
    "status": "processing",
    "created_at": "2025-08-29T12:00:00.000Z"
  }
}

Status Codes

201 - Content created successfully
400 - Invalid input data
401 - Unauthorized
500 - Internal server error

Get Video Feed

Get personalized video feed.

Endpoint: GET /brok/api/v1/feeds

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}
x-language	string	❌	Language preference (en, vi, ko)

Request Parameters

Name	Type	Required	Description
cursor	string	❌	Pagination cursor
per_page	number	❌	Items per page (default: 10)

Response Example

{
  "success": true,
  "message": "Video feed retrieved successfully",
  "data": {
    "items": [
      {
        "id": "48c8c3b8-850d-48b9-97ce-ba353a075792",
        "price": 123313,
        "unit_price": "USD",
        "area": 12313,
        "unit_area": "ft²",
        "video": {
          "thumbnail_url": "https://d37k5wtx5jh88r.cloudfront.net/.../thumb.webp",
          "url": "https://d37k5wtx5jh88r.cloudfront.net/.../master.m3u8"
        },
        "content_info": [
          {
            "lang": "en",
            "project_name": "Luxury Apartment",
            "location": "Đà Nẵng, Vietnam"
          }
        ],
        "uploader": {
          "name": "John Doe",
          "avatar": "https://example.com/avatar.jpg"
        },
        "reaction_count": 25,
        "created_at": "2025-08-29T07:04:29.454Z"
      }
    ],
    "next_cursor": "eyJpZCI6IjY0ZjBjOGE5YTBiOGIwZTZjOGUzZjRhMSJ9",
    "has_more": true
  }
}

Status Codes

200 - Feed retrieved successfully
401 - Unauthorized
500 - Internal server error

Comments

Create Comment

Create a new comment or a reply.

Endpoint: POST /sns/api/v1/comments

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}

Request Parameters

Name	Type	Required	Description
contentId	string	✅	ID of content being commented on
msg	string	✅	Comment message text
parentId	string	❌	Parent comment ID (for replies)

Request Example

{
  "contentId": "48c8c3b8-850d-48b9-97ce-ba353a075792",
  "msg": "Beautiful property! Great location.",
  "parentId": null
}

Response Example

{
  "success": true,
  "message": "Comment created successfully",
  "data": {
    "_id": "64f0c8a9a0b8b0e6c8e3f4a1",
    "contentId": "48c8c3b8-850d-48b9-97ce-ba353a075792",
    "msg": "Beautiful property! Great location.",
    "author": {
      "userId": "496a651c-6061-704e-3884-d420f8cfb352",
      "name": "John Doe",
      "avatarUrl": "https://d37k5wtx5jh88r.cloudfront.net/.../avatar.jpeg"
    },
    "reactions": [],
    "replyCount": 0,
    "createdAt": "2025-08-29T10:15:30.123Z",
    "updatedAt": "2025-08-29T10:15:30.123Z"
  }
}

Status Codes

201 - Comment created successfully
400 - Invalid input data
401 - Unauthorized
404 - Content not found
500 - Internal server error

Get Comments

Get all top-level comments for a piece of content.

Endpoint: GET /sns/api/v1/comments/{contentId}

Path Parameters

Name	Type	Required	Description
contentId	string	✅	Content ID to get comments for

Request Parameters

Name	Type	Required	Description
limit	number	❌	Number of comments to return
cursor	string	❌	Cursor for pagination

Response Example

{
  "success": true,
  "message": "Comments retrieved successfully",
  "data": {
    "comments": [
      {
        "_id": "64f0c8a9a0b8b0e6c8e3f4a1",
        "contentId": "48c8c3b8-850d-48b9-97ce-ba353a075792",
        "msg": "Beautiful property!",
        "author": {
          "userId": "496a651c-6061-704e-3884-d420f8cfb352",
          "name": "John Doe",
          "avatarUrl": "https://example.com/avatar.jpg"
        },
        "reactions": [
          {
            "author": {
              "userId": "other-user-id",
              "name": "Jane Smith"
            },
            "emoji": "👍"
          }
        ],
        "replyCount": 3,
        "createdAt": "2025-08-29T10:15:30.123Z"
      }
    ],
    "hasMore": true,
    "nextCursor": "eyJpZCI6IjY0ZjBjOGE5YTBiOGIwZTZjOGUzZjRhMSJ9"
  }
}

Status Codes

200 - Comments retrieved successfully
404 - Content not found
500 - Internal server error

Follow User

Follow a user.

Endpoint: POST /auth/api/v1/users/{userId}/follow

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}
X-User-ID	string	✅	Current user's ID

Path Parameters

Name	Type	Required	Description
userId	string	✅	ID of user to follow

Response Example

{
  "success": true,
  "message": "User followed successfully",
  "data": {
    "follower_id": "496a651c-6061-704e-3884-d420f8cfb352",
    "following_id": "target-user-id",
    "created_at": "2025-08-29T09:00:00.000Z"
  }
}

Status Codes

200 - Successfully followed user
400 - Already following or invalid user ID
401 - Unauthorized
404 - User not found
429 - Rate limit exceeded
500 - Internal server error

Chat System

Send Message

Send a message in a chat room.

Endpoint: POST /sns/api/v1/chat/messages

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}

Request Parameters

Name	Type	Required	Description
roomId	string	✅	Chat room ID
msg	string	❌	Text message
attachments	array	❌	File attachments

Request Example

{
  "roomId": "room-id-123",
  "msg": "Check out this amazing property!",
  "attachments": [
    {
      "type": "image",
      "fileName": "property.jpg",
      "url": "https://example.com/image.jpg",
      "fileSize": 1024000
    }
  ]
}

Response Example

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "_id": "message-id-123",
    "roomId": "room-id-123",
    "msg": "Check out this amazing property!",
    "sender": {
      "userId": "496a651c-6061-704e-3884-d420f8cfb352",
      "name": "John Doe",
      "picture": "https://example.com/avatar.jpg"
    },
    "attachments": [
      {
        "type": "image",
        "fileName": "property.jpg",
        "url": "https://example.com/image.jpg",
        "downloadable": true
      }
    ],
    "reactions": [],
    "createdAt": "2025-08-29T12:00:00.000Z"
  }
}

Status Codes

201 - Message sent successfully
400 - Invalid input data
401 - Unauthorized
403 - Not member of chat room
404 - Chat room not found
500 - Internal server error

File Upload

Upload File

Upload and process media files.

Endpoint: POST /file-processing/api/v1/upload

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}

Request Parameters

Name	Type	Required	Description
file	file	✅	Media file to upload
type	string	✅	File type (image, video, document)
metadata	object	❌	Additional file metadata

Response Example

{
  "success": true,
  "message": "File uploaded successfully",
  "data": {
    "file_id": "file-123",
    "url": "https://d37k5wtx5jh88r.cloudfront.net/file.jpg",
    "type": "image",
    "size": 1024000,
    "processing_status": "completed",
    "metadata": {
      "width": 1920,
      "height": 1080,
      "format": "jpeg"
    }
  }
}

Status Codes

201 - File uploaded successfully
400 - Invalid file type or size
401 - Unauthorized
413 - File too large
500 - Upload failed

TikTok Integration

Get TikTok Auth URL

Endpoint: GET /brok/api/v1/tiktok/auth

Response Example

{
  "success": true,
  "message": "TikTok auth URL generated",
  "data": {
    "url": "https://www.tiktok.com/auth/authorize/?client_key=..."
  }
}

Upload to TikTok

Endpoint: POST /brok/api/v1/tiktok/upload

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}
x-user-id	string	✅	User's ID

Request Example

{
  "id": "48c8c3b8-850d-48b9-97ce-ba353a075792",
  "title": "Amazing Property in Da Nang",
  "description": "Check out this beautiful apartment with ocean views",
  "tags": ["#property", "#danang", "#realestate"]
}

YouTube Integration

Get YouTube Auth URL

Endpoint: GET /brok/api/v1/youtube/auth

Upload to YouTube

Endpoint: POST /brok/api/v1/youtube/upload

Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer {access_token}
x-user-id	string	✅	User's ID

Error Handling

All error responses follow this consistent format:

{
  "success": false,
  "error_code": "auth.error.invalid_credentials",
  "message": "Invalid phone number or password",
  "details": {
    "field": "phone_number",
    "constraint": "User not found"
  },
  "timestamp": "2025-08-29T16:00:00.000Z"
}

Common Status Codes

Success Codes

200 OK - Request successful
201 Created - Resource created successfully
204 No Content - Request successful, no content to return

Client Error Codes

400 Bad Request - Invalid request parameters or body
401 Unauthorized - Missing or invalid authentication token
403 Forbidden - Insufficient permissions for the operation
404 Not Found - Requested resource does not exist
409 Conflict - Resource already exists or conflict with current state
413 Payload Too Large - File size exceeds limit
422 Unprocessable Entity - Valid request format but invalid data
429 Too Many Requests - Rate limit exceeded

Server Error Codes

500 Internal Server Error - Unexpected server error
502 Bad Gateway - Service unavailable or gateway error
503 Service Unavailable - Service temporarily unavailable

Rate Limiting

Most endpoints have rate limiting applied:

Endpoint Type	Rate Limit
Authentication endpoints	5 requests/minute per IP
Content creation	10 requests/minute per user
Comments	30 requests/minute per user
File uploads	5 requests/minute per user
General API calls	100 requests/minute per user

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1693392000

Multi-language Support

Many endpoints support multiple languages through headers:

Supported Languages

en: English (default)
vi: Vietnamese
ko: Korean

Request Header

x-language: vi

Content will be returned in the specified language when available, falling back to English if translation is not available.

Base URLs​

Authentication​

Authentication​

Send OTP​

Request Parameters​

Request Example​

Response Example​

Status Codes​

Verify OTP​

Request Parameters​

Request Example​

Response Example​

Status Codes​

Register User​

Request Parameters​

Request Example​

Response Example​

Status Codes​

User Login​

Request Parameters​

Request Example​

Response Example​

Status Codes​

Refresh Token​

Headers​

Request Parameters​

Request Example​

Response Example​

Status Codes​

User Logout​

Headers​

Response Example​

Status Codes​

Forgot Password​

Request Parameters​

Request Example​

Response Example​

Status Codes​

Confirm Forgot Password​

Request Parameters​

Request Example​

Response Example​

Status Codes​

User Management​

Get Current User​

Headers​

Response Example​

Status Codes​

Update Current User​

Headers​

Request Parameters​

Request Example​

Response Example​

Status Codes​

Update Avatar​

Headers​

Request Parameters​

Response Example​

Status Codes​

Change Password​

Headers​

Request Parameters​

Request Example​

Response Example​

Status Codes​

Authorization​

Get Permissions​

Request Parameters​

Response Example​

Status Codes​

Create Permission​

Headers​

Request Parameters​

Request Example​

Response Example​

Status Codes​

Get Roles​

Headers​

Response Example​

Status Codes​

Base URLs

Authentication

Authentication

Send OTP

Request Parameters

Request Example

Response Example

Status Codes

Verify OTP

Request Parameters

Request Example

Response Example

Status Codes

Register User

Request Parameters

Request Example

Response Example

Status Codes

User Login

Request Parameters

Request Example

Response Example

Status Codes

Refresh Token

Headers

Request Parameters

Request Example

Response Example

Status Codes

User Logout

Headers

Response Example

Status Codes

Forgot Password

Request Parameters

Request Example

Response Example

Status Codes

Confirm Forgot Password

Request Parameters

Request Example

Response Example

Status Codes

User Management

Get Current User

Headers

Response Example

Status Codes

Update Current User

Headers

Request Parameters

Request Example

Response Example

Status Codes

Update Avatar

Headers

Request Parameters

Response Example

Status Codes

Change Password

Headers

Request Parameters

Request Example

Response Example

Status Codes

Authorization

Get Permissions

Request Parameters

Response Example

Status Codes

Create Permission

Headers

Request Parameters

Request Example

Response Example

Status Codes

Get Roles

Headers

Response Example

Status Codes