openapi: 3.0.3 info: title: 1000-Messenger API description: | Real-time messenger application API with support for direct messaging, group chats, file uploads, reactions, read receipts, and presence tracking. ## Authentication This API uses Bearer token authentication. Include the JWT token in the Authorization header: ``` Authorization: Bearer ``` ## Rate Limiting - Login attempts: 5 per 15 minutes per username - Message sending: 10 per second per user - Contact requests: 50 per day per user - Image uploads: 10 per minute per user - General operations: 100 per minute per user ## WebSocket Connection Real-time features are available via Socket.IO at `/socket.io`. Connect with JWT token for authentication. version: 1.0.0 contact: name: API Support email: support@1000-messenger.app license: name: MIT url: https://opensource.org/licenses/MIT servers: - url: http://localhost:3000 description: Local development server - url: https://api.1000-messenger.app description: Production server tags: - name: Authentication description: User registration, login, and session management - name: Users description: User profile management and search - name: Contacts description: Contact management and friend requests - name: Chats description: Direct and group chat management - name: Messages description: Message CRUD operations and search - name: Attachments description: File upload and management - name: Reactions description: Emoji reactions on messages - name: Health description: API health and status checks paths: # ============================================================================ # Authentication Endpoints # ============================================================================ /api/auth/register: post: tags: - Authentication summary: Register a new user description: Create a new user account with username and password operationId: register requestBody: required: true content: application/json: schema: type: object required: - username - password - passwordConfirm properties: username: type: string minLength: 3 maxLength: 50 pattern: '^[a-zA-Z0-9_]+$' example: john_doe password: type: string minLength: 8 example: SecurePass123! passwordConfirm: type: string example: SecurePass123! displayName: type: string maxLength: 100 example: John Doe responses: '201': description: User created successfully content: application/json: schema: type: object properties: user: $ref: '#/components/schemas/User' accessToken: type: string refreshToken: type: string '400': $ref: '#/components/responses/BadRequest' '409': description: Username already exists content: application/json: schema: $ref: '#/components/schemas/Error' /api/auth/login: post: tags: - Authentication summary: Login to existing account description: Authenticate with username and password to receive JWT tokens operationId: login requestBody: required: true content: application/json: schema: type: object required: - username - password properties: username: type: string example: john_doe password: type: string example: SecurePass123! responses: '200': description: Login successful content: application/json: schema: type: object properties: user: $ref: '#/components/schemas/User' accessToken: type: string refreshToken: type: string '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' /api/auth/refresh: post: tags: - Authentication summary: Refresh access token description: Get a new access token using a valid refresh token operationId: refreshToken requestBody: required: true content: application/json: schema: type: object required: - refreshToken properties: refreshToken: type: string responses: '200': description: Token refreshed successfully content: application/json: schema: type: object properties: accessToken: type: string refreshToken: type: string '401': $ref: '#/components/responses/Unauthorized' /api/auth/logout: post: tags: - Authentication summary: Logout description: Invalidate current session and tokens operationId: logout security: - bearerAuth: [] responses: '200': description: Logout successful '401': $ref: '#/components/responses/Unauthorized' # ============================================================================ # User Endpoints # ============================================================================ /api/users/me: get: tags: - Users summary: Get current user profile description: Retrieve the authenticated user's profile information operationId: getCurrentUser security: - bearerAuth: [] responses: '200': description: User profile retrieved content: application/json: schema: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/Unauthorized' put: tags: - Users summary: Update current user profile description: Update display name and status operationId: updateCurrentUser security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: displayName: type: string maxLength: 100 status: type: string enum: [online, away, offline] responses: '200': description: Profile updated content: application/json: schema: $ref: '#/components/schemas/User' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' /api/users/search: get: tags: - Users summary: Search for users description: Search users by username (partial, case-insensitive) operationId: searchUsers security: - bearerAuth: [] parameters: - name: query in: query required: true schema: type: string minLength: 1 - name: limit in: query schema: type: integer default: 20 maximum: 100 responses: '200': description: Search results content: application/json: schema: type: object properties: users: type: array items: $ref: '#/components/schemas/User' '401': $ref: '#/components/responses/Unauthorized' /api/users/{userId}: get: tags: - Users summary: Get user by ID description: Retrieve another user's profile (must be contact or in shared chat) operationId: getUserById security: - bearerAuth: [] parameters: - name: userId in: path required: true schema: type: string format: uuid responses: '200': description: User profile retrieved content: application/json: schema: $ref: '#/components/schemas/User' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' # ============================================================================ # Contact Endpoints # ============================================================================ /api/contacts: get: tags: - Contacts summary: Get all contacts description: Retrieve all accepted contacts for the current user operationId: getContacts security: - bearerAuth: [] responses: '200': description: List of contacts content: application/json: schema: type: object properties: contacts: type: array items: $ref: '#/components/schemas/Contact' post: tags: - Contacts summary: Send contact request description: Send a contact/friend request to another user operationId: sendContactRequest security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - contactId properties: contactId: type: string format: uuid responses: '201': description: Contact request sent content: application/json: schema: $ref: '#/components/schemas/Contact' '400': $ref: '#/components/responses/BadRequest' '429': $ref: '#/components/responses/TooManyRequests' /api/contacts/pending: get: tags: - Contacts summary: Get pending contact requests description: Retrieve all pending incoming contact requests operationId: getPendingRequests security: - bearerAuth: [] responses: '200': description: List of pending requests content: application/json: schema: type: object properties: requests: type: array items: $ref: '#/components/schemas/Contact' /api/contacts/{contactId}/accept: put: tags: - Contacts summary: Accept contact request description: Accept a pending contact request operationId: acceptContactRequest security: - bearerAuth: [] parameters: - name: contactId in: path required: true schema: type: string format: uuid responses: '200': description: Contact request accepted content: application/json: schema: $ref: '#/components/schemas/Contact' '404': $ref: '#/components/responses/NotFound' /api/contacts/{contactId}/reject: put: tags: - Contacts summary: Reject contact request description: Reject a pending contact request operationId: rejectContactRequest security: - bearerAuth: [] parameters: - name: contactId in: path required: true schema: type: string format: uuid responses: '200': description: Contact request rejected '404': $ref: '#/components/responses/NotFound' /api/contacts/{contactId}: delete: tags: - Contacts summary: Remove contact description: Remove a contact from your list (bidirectional) operationId: removeContact security: - bearerAuth: [] parameters: - name: contactId in: path required: true schema: type: string format: uuid responses: '200': description: Contact removed '404': $ref: '#/components/responses/NotFound' # ============================================================================ # Chat Endpoints # ============================================================================ /api/chats: get: tags: - Chats summary: Get all chats description: Retrieve all chats (direct and group) for the current user operationId: getChats security: - bearerAuth: [] responses: '200': description: List of chats content: application/json: schema: type: object properties: chats: type: array items: $ref: '#/components/schemas/Chat' /api/chats/direct: post: tags: - Chats summary: Create direct chat description: Create or retrieve existing direct chat with a contact operationId: createDirectChat security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - participantId properties: participantId: type: string format: uuid responses: '200': description: Direct chat created or retrieved content: application/json: schema: $ref: '#/components/schemas/Chat' /api/chats/group: post: tags: - Chats summary: Create group chat description: Create a new group chat with multiple participants operationId: createGroupChat security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - name - participantIds properties: name: type: string maxLength: 100 participantIds: type: array items: type: string format: uuid minItems: 1 maxItems: 299 responses: '201': description: Group chat created content: application/json: schema: $ref: '#/components/schemas/Chat' '400': $ref: '#/components/responses/BadRequest' /api/chats/{chatId}: get: tags: - Chats summary: Get chat by ID description: Retrieve chat details and participants operationId: getChatById security: - bearerAuth: [] parameters: - name: chatId in: path required: true schema: type: string format: uuid responses: '200': description: Chat retrieved content: application/json: schema: $ref: '#/components/schemas/Chat' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' put: tags: - Chats summary: Update group chat description: Update group name or avatar (owner only) operationId: updateGroupChat security: - bearerAuth: [] parameters: - name: chatId in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object properties: name: type: string maxLength: 100 responses: '200': description: Chat updated content: application/json: schema: $ref: '#/components/schemas/Chat' '403': $ref: '#/components/responses/Forbidden' delete: tags: - Chats summary: Delete group chat description: Delete a group chat (owner only) operationId: deleteGroupChat security: - bearerAuth: [] parameters: - name: chatId in: path required: true schema: type: string format: uuid responses: '200': description: Chat deleted '403': $ref: '#/components/responses/Forbidden' # ============================================================================ # Message Endpoints # ============================================================================ /api/chats/{chatId}/messages: get: tags: - Messages summary: Get messages in chat description: Retrieve paginated messages from a chat operationId: getMessages security: - bearerAuth: [] parameters: - name: chatId in: path required: true schema: type: string format: uuid - name: limit in: query schema: type: integer default: 50 maximum: 100 - name: cursor in: query description: Cursor for pagination (message ID) schema: type: string format: uuid responses: '200': description: Messages retrieved content: application/json: schema: type: object properties: messages: type: array items: $ref: '#/components/schemas/Message' nextCursor: type: string format: uuid nullable: true post: tags: - Messages summary: Send message description: Send a text or image message to a chat operationId: sendMessage security: - bearerAuth: [] parameters: - name: chatId in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - content properties: content: type: string maxLength: 10000 contentType: type: string enum: [text, image] default: text replyToId: type: string format: uuid metadata: type: object responses: '201': description: Message sent content: application/json: schema: $ref: '#/components/schemas/Message' '400': $ref: '#/components/responses/BadRequest' '429': $ref: '#/components/responses/TooManyRequests' /api/messages/{messageId}: put: tags: - Messages summary: Edit message description: Edit your own message (owner only) operationId: editMessage security: - bearerAuth: [] parameters: - name: messageId in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - content properties: content: type: string maxLength: 10000 responses: '200': description: Message edited content: application/json: schema: $ref: '#/components/schemas/Message' '403': $ref: '#/components/responses/Forbidden' delete: tags: - Messages summary: Delete message description: Delete your own message (soft delete) operationId: deleteMessage security: - bearerAuth: [] parameters: - name: messageId in: path required: true schema: type: string format: uuid responses: '200': description: Message deleted '403': $ref: '#/components/responses/Forbidden' /api/messages/search: get: tags: - Messages summary: Search messages description: Full-text search across all messages operationId: searchMessages security: - bearerAuth: [] parameters: - name: query in: query required: true schema: type: string - name: chatId in: query description: Optional - filter by specific chat schema: type: string format: uuid - name: limit in: query schema: type: integer default: 100 maximum: 100 responses: '200': description: Search results content: application/json: schema: type: object properties: messages: type: array items: $ref: '#/components/schemas/Message' # ============================================================================ # Reaction Endpoints # ============================================================================ /api/messages/{messageId}/reactions: post: tags: - Reactions summary: Add reaction description: Add an emoji reaction to a message operationId: addReaction security: - bearerAuth: [] parameters: - name: messageId in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: - emoji properties: emoji: type: string maxLength: 10 responses: '201': description: Reaction added content: application/json: schema: $ref: '#/components/schemas/Reaction' /api/messages/{messageId}/reactions/{reactionId}: delete: tags: - Reactions summary: Remove reaction description: Remove your reaction from a message operationId: removeReaction security: - bearerAuth: [] parameters: - name: messageId in: path required: true schema: type: string format: uuid - name: reactionId in: path required: true schema: type: string format: uuid responses: '200': description: Reaction removed # ============================================================================ # Health Endpoints # ============================================================================ /api/health: get: tags: - Health summary: Health check description: Check API health and status operationId: healthCheck responses: '200': description: Service is healthy content: application/json: schema: type: object properties: status: type: string example: healthy timestamp: type: string format: date-time database: type: object properties: connected: type: boolean redis: type: object properties: connected: type: boolean uptime: type: number # ============================================================================ # Component Schemas # ============================================================================ components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT schemas: User: type: object properties: id: type: string format: uuid username: type: string displayName: type: string nullable: true avatarUrl: type: string nullable: true status: type: string enum: [online, away, offline] lastSeen: type: string format: date-time nullable: true createdAt: type: string format: date-time Contact: type: object properties: id: type: string format: uuid userId: type: string format: uuid contactId: type: string format: uuid status: type: string enum: [pending, accepted, rejected] contact: $ref: '#/components/schemas/User' createdAt: type: string format: date-time Chat: type: object properties: id: type: string format: uuid type: type: string enum: [direct, group] name: type: string nullable: true slug: type: string nullable: true avatarUrl: type: string nullable: true ownerId: type: string format: uuid nullable: true participants: type: array items: $ref: '#/components/schemas/ChatParticipant' lastMessageAt: type: string format: date-time nullable: true createdAt: type: string format: date-time ChatParticipant: type: object properties: id: type: string format: uuid userId: type: string format: uuid role: type: string enum: [owner, admin, member] user: $ref: '#/components/schemas/User' joinedAt: type: string format: date-time Message: type: object properties: id: type: string format: uuid chatId: type: string format: uuid senderId: type: string format: uuid content: type: string contentType: type: string enum: [text, image, system] metadata: type: object replyToId: type: string format: uuid nullable: true isEdited: type: boolean editedAt: type: string format: date-time nullable: true reactions: type: array items: $ref: '#/components/schemas/Reaction' sender: $ref: '#/components/schemas/User' createdAt: type: string format: date-time Reaction: type: object properties: id: type: string format: uuid messageId: type: string format: uuid userId: type: string format: uuid emoji: type: string createdAt: type: string format: date-time Error: type: object properties: error: type: string message: type: string statusCode: type: integer details: type: object responses: BadRequest: description: Bad request - validation error content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized - missing or invalid token content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden - insufficient permissions content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' TooManyRequests: description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error'