Chirpy is a social media API that allows users to create and manage short messages called \"chirps\". The API provides endpoints for user management, chirp operations, health monitoring, and administrative functions.
\nAll API endpoints use the following base URL pattern:
\n\n\nSet the baseURL variable in your Postman environment to point to your Chirpy server instance.
Authentication requirements vary by endpoint:
\nPublic endpoints: No authentication required (health check, app root)
\nUser endpoints: Require user authentication token
\nAdmin endpoints: Require administrative privileges
\nInclude authentication tokens in the Authorization header:
Authorization: Bearer <your_token>\n\nRoot endpoint - Returns the application root page or status.
\nEndpoint: /app
Method: GET
Authentication: None required
\nUser management endpoints for registration and authentication.
\nCreate User - Register a new user account.
\nEndpoint: /api/users
Method: POST
Authentication: None required
\nRequest Body:
\n{\n \"email\": \"user@example.com\",\n \"password\": \"securepassword\"\n}\n\nResponse: Returns the created user object with user ID and details.
\nLogin User - Authenticate a user and receive an access token.
\nEndpoint: /api/login
Method: POST
Authentication: None required
\nRequest Body:
\n{\n \"email\": \"user@example.com\",\n \"password\": \"securepassword\"\n}\n\nResponse: Returns authentication token and user information.
\nEndpoints for creating and retrieving chirps (short messages).
\nCreate Chirp - Post a new chirp message.
\nEndpoint: /api/chirps
Method: POST
Authentication: Required (Bearer token)
\nRequest Body:
\n{\n \"body\": \"This is my chirp message\"\n}\n\nResponse: Returns the created chirp with ID, timestamp, and content.
\nGet All Chirps - Retrieve all chirps from all users.
\nEndpoint: /api/chirps
Method: GET
Authentication: None required
\nQuery Parameters:
\nsort (optional): Sort order for chirps (e.g., asc, desc)Response: Returns an array of chirp objects.
\nGet Chirp by ID - Retrieve a specific chirp by its ID.
\nEndpoint: /api/chirps/:chirpID
Method: GET
Authentication: None required
\nPath Parameters:
\nchirpID (required): The unique identifier of the chirpResponse: Returns the requested chirp object.
\nGet Chirps by User ID - Retrieve all chirps from a specific user.
\nEndpoint: /api/users/{{userID}}/chirps
Method: GET
Authentication: None required
\nPath Parameters:
\nuserID (required): The unique identifier of the userResponse: Returns an array of chirps created by the specified user.
\nGet My Chirps - Retrieve all chirps from the authenticated user.
\nEndpoint: /api/me/chirps
Method: GET
Authentication: Required (Bearer token)
\nResponse: Returns an array of chirps created by the authenticated user.
\nHealth Check - Check the health status of the API.
\nEndpoint: /api/healthz
Method: GET
Authentication: None required
\nResponse: Returns the health status of the service (typically 200 OK).
Administrative endpoints for monitoring and maintenance.
\nMetrics - Retrieve application metrics and statistics.
\nEndpoint: /admin/metrics
Method: GET
Authentication: Required (Admin privileges)
\nResponse: Returns metrics data including request counts, performance statistics, and system health.
\nReset - Reset the application state (typically used in development/testing).
\nEndpoint: /admin/reset
Method: POST
Authentication: Required (Admin privileges)
\nResponse: Confirms the reset operation.
\nThe API uses standard HTTP status codes:
\n200 OK: Request succeeded
\n201 Created: Resource created successfully
\n400 Bad Request: Invalid request parameters or body
\n401 Unauthorized: Authentication required or failed
\n403 Forbidden: Insufficient permissions
\n404 Not Found: Resource not found
\n500 Internal Server Error: Server error
\nError responses include a JSON body with details:
\n{\n \"error\": \"Error message describing what went wrong\"\n}\n\nRate limiting policies may apply to prevent abuse. Check response headers for rate limit information:
\nX-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Remaining requests in current window
X-RateLimit-Reset: Time when the rate limit resets
Set up your environment: Create a Postman environment and set the baseURL variable to your Chirpy server URL
Create a user: Use the POST /api/users endpoint to register
Login: Use the POST /api/login endpoint to get your authentication token
Save your token: Store the token in an environment variable for authenticated requests
\nStart chirping: Use the authenticated endpoints to create and manage chirps
\nFor issues, questions, or feature requests, please contact the development team or refer to the project repository.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Chirpy API Documentation","slug":"chirpy-api-documentation"}],"owner":"46941071","collectionId":"35666e2f-7d3b-4e06-8871-8eed9cf121ae","publishedId":"2sBXc8qizy","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-02-08T19:15:13.000Z"},"item":[{"name":"api","item":[{"name":"Users","item":[{"name":"CreateUser","id":"63656af6-2a10-46e4-87f4-7adb13265026","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"password\": \"pass5\",\r\n \"email\": \"lane05@example.com\"\r\n}","options":{"raw":{"language":"json"}}},"url":"/api/users","description":"POST /api/users
Create a new user account.
\nRequest Body:
\n{\n \"email\": \"user@example.com\",\n \"password\": \"securepassword\"\n}\n\nResponse: 201 Created
{\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"email\": \"user@example.com\",\n \"is_chirpy_red\": false\n}\n\nPOST /api/login
Authenticate and receive access + refresh tokens.
\nRequest Body:
\n{\n \"email\": \"user@example.com\",\n \"password\": \"securepassword\"\n}\n\nResponse: 200 OK
{\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"email\": \"user@example.com\",\n \"is_chirpy_red\": false,\n \"token\": \"jwt_access_token\",\n \"refresh_token\": \"refresh_token_string\"\n}\n\nPUT /api/users
Update user email and/or password.
\nAuth Required: Yes
\nRequest Body:
\n{\n \"email\": \"newemail@example.com\",\n \"password\": \"newpassword\"\n}\n\nResponse: 200 OK
{\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"email\": \"newemail@example.com\",\n \"is_chirpy_red\": false\n}\n\nPOST /api/users/{userID}
To delete a user.
\nAuth Required: Yes
\nPath Parameters:
\nuserID - User UUID to deleteResponse: 204 No Content
GET /api/users
Get user profile.
Auth Required: Yes
Response: 200 OK
{\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"email\": \"user@example.com\",\n \"is_chirpy_red\": false\n}\n\nPOST /api/chirps
Post a new chirp (max 140 characters).
\nAuth Required: Yes
\nRequest Body:
\n{\n \"body\": \"This is my chirp!\"\n}\nResponse: 201 Created
{\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"body\": \"This is my chirp!\",\n \"user_id\": \"uuid\"\n}\nGET /api/chirps
Retrieve all chirps (public).
\nAuth Required: Yes
\nQuery Parameters:
\nsort - asc or desc (optional)
author_id - Filter by user UUID (optional)
Response: 200 OK
[\n {\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"body\": \"chirp text\",\n \"user_id\": \"uuid\"\n }\n]\n\nEndpoint to retrieve a specific chirp by ID
\nBearer token authentication required in the Authorization header.
\n:chirpID - The unique identifier of the chirp\n\n{\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"body\": \"chirp text\",\n \"user_id\": \"uuid\"\n}\n\nEndpoint to retrieve all chirps by a specific user
\nBearer token authentication required in the Authorization header.
\n:userID - The unique identifier of the user\n\n[\n {\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"body\": \"chirp text\",\n \"user_id\": \"uuid\"\n }\n]\n\nEndpoint to retrieve authenticated user's chirps
\nBearer token authentication required in the Authorization header.
\nThis endpoint uses the authenticated user's token to retrieve their chirps.
\n[\n {\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"body\": \"chirp text\",\n \"user_id\": \"uuid\"\n }\n]\n\nEndpoint to update an existing chirp
\nBearer token authentication required. Chirpy Red membership required to update chirps.
\nPath: :chirpID - The unique identifier of the chirp to update\n{\n \"body\": \"updated text\"\n}\n{\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"body\": \"updated text\",\n \"user_id\": \"uuid\"\n}\nDELETE /api/chirps/{chirpID}
Delete your own chirp.
\nAuth Required: Yes
\nPath Parameters:
\nchirpID - Chirp UUID**Response:
**204 No Content
403 Forbidden
Endpoints for Chirps
\n","_postman_id":"b45c9479-c044-4e38-981e-77348ac4d37c"},{"name":"Health","item":[{"name":"healthz","id":"77e7af1c-959b-460e-ab8e-60813917cd8b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/api/healthz","description":"GET /api/healthz
Service health endpoint.
\nResponse: 200 OK
{\n \"status\": \"ok\"\n}\nPOST /api/polka/webhooks
Webhook endpoint for payment provider to upgrade users to Chirpy Red.
\nHeaders:
\nAuthorization: ApiKey <polka_api_key>\nRequest Body:
\n{\n \"event\": \"user.upgraded\",\n \"data\": {\n \"user_id\": \"uuid\"\n }\n}\nResponse:
\n204 No Content - Success or ignored event401 Unauthorized - Invalid API key404 Not Found - User not foundGET /api/feed
Get chronological feed of chirps from users you follow.
\nAuth Required: Yes
\nQuery Parameters:
\nlimit - Number of chirps (default: 20)
offset - Pagination offset (default: 0)
Response: 200 OK
[\n {\n \"id\": \"uuid\",\n \"created_at\": \"timestamp\",\n \"updated_at\": \"timestamp\",\n \"body\": \"chirp text\",\n \"user_id\": \"uuid\",\n \"author_email\": \"author@example.com\"\n }\n]\n\nSorted by most recent first
\n","urlObject":{"path":["api","feed"],"host":[""],"query":[],"variable":[]}},"response":[],"_postman_id":"d239f856-9df7-4caa-8c7f-46f125d206e4"}],"id":"251e02df-c1fb-4028-bd78-2e22e7c17a47","_postman_id":"251e02df-c1fb-4028-bd78-2e22e7c17a47","description":""},{"name":"Follows","item":[{"name":"FollowUser","id":"e8e67145-49ed-4adc-9df3-284b962426c0","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJjaGlycHkiLCJzdWIiOiI1NGFhNWRhZi02MDQyLTQ0OGEtOGY4MC1iMjIzZjgzYmQxYjciLCJleHAiOjE3NzEyODE2NDEsImlhdCI6MTc3MTI3ODA0MX0.h2CKHm-VmIa_fomiBBLCIUr72fi7BDQ2QFDfDCg71JM","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"followee_id\": \"b9af1149-ef14-44e4-a142-ac6f4e282761\"\r\n}","options":{"raw":{"language":"json"}}},"url":"/api/follow","description":"POST /api/follow
Follow another user to see their chirps in your feed.
\nAuth Required: Yes
\nRequest Body:
\n{\n \"followee_id\": \"uuid\"\n}\n\nResponse: 204 No Content
Errors:
\n400 - Cannot follow yourself
500 - Server error
DELETE /api/follow/{userID}
Stop following a user.
\nAuth Required: Yes
\nPath Parameters:
\nuserID - User UUID to unfollowResponse: 204 No Content
GET /api/followers
Get list of users who follow you.
\nAuth Required: Yes
\nResponse: 200 OK
{\n \"followers\": [\n {\n \"id\": \"uuid\",\n \"email\": \"user@example.com\",\n \"is_chirpy_red\": false,\n \"created_at\": \"timestamp\",\n \"followed_at\": \"timestamp\",\n \"total_followers\": 10\n }\n ],\n \"total\": 10\n}\n\nGET /api/following
Get list of users you follow.
\nAuth Required: Yes
\nResponse: 200 OK
{\n \"following\": [\n {\n \"id\": \"uuid\",\n \"email\": \"user@example.com\",\n \"is_chirpy_red\": false,\n \"created_at\": \"timestamp\",\n \"followed_at\": \"timestamp\",\n \"total_following\": 15\n }\n ],\n \"total\": 15\n}\n\nPOST /api/refresh
Get a new access token using refresh token.
\nHeaders:
\nAuthorization: Bearer <refresh_token>\n\nResponse: 200 OK
{\n \"token\": \"new_jwt_access_token\"\n}\n\nPOST /api/revoke
Revoke a refresh token (logout).
\nHeaders:
\nAuthorization: Bearer <refresh_token>\n\nResponse: 204 No Content
GET /admin/metrics
View server metrics (hit counter).
\nResponse: 200 OK (HTML page)
POST /admin/reset
Reset hit counter to zero.
\nResponse: 200 OK (HTML page)