01
Endpoints
| GET | /public/v2/users | public | List all users — supports pagination & filtering |
| POST | /public/v2/users | token | Create a new user |
| GET | /public/v2/users/:id | public | Fetch single user by ID |
| PUT | /public/v2/users/:id | token | Full replace — all fields required |
| PATCH | /public/v2/users/:id | token | Partial update — send only changed fields |
| DELETE | /public/v2/users/:id | token | Remove user permanently |
02
Authentication
GET requests are public — no token needed. Open them straight in Postman or your browser.
POST, PUT, PATCH, DELETE require an Authorization: Bearer <token> header. Any non-empty string works — demo-token, abc123, your own name, anything.
One exception: blocked-token deliberately returns 403 Forbidden — useful for testing error-handling flows.
03
User Schema
{
"id": 1001,
"name": "Aarav Sharma",
"email": "aarav.sharma@example.com",
"gender": "male" // "male" | "female"
"status": "active" // "active" | "inactive"
}
04
Query Parameters
| ?name= | Filter by name (partial match). e.g. ?name=aarav |
| ?email= | Filter by email. e.g. ?email=example.com |
| ?gender= | Filter by gender — male or female |
| ?status= | Filter by status — active or inactive |
| ?page= | Page number. Default: 1 |
| ?per_page= | Results per page. Default: 10 Max: 100 |
05
cURL Examples
curl https://gorest.in/public/v2/users
curl "https://gorest.in/public/v2/users?page=1&per_page=10&status=active"
curl https://gorest.in/public/v2/users/1001
curl -X POST https://gorest.in/public/v2/users -H "Content-Type: application/json" -H "Authorization: Bearer demo-token" -d '{"name":"Naveen Kumar","email":"nk@test.com","gender":"male","status":"active"}'
curl -X PATCH https://gorest.in/public/v2/users/1001 -H "Content-Type: application/json" -H "Authorization: Bearer demo-token" -d '{"status":"inactive"}'
curl -X DELETE https://gorest.in/public/v2/users/1001 -H "Authorization: Bearer demo-token"
06
HTTP Status Codes
2xx — 3xx Success
200OKGET / PUT / PATCH
201CreatedPOST
204No ContentDELETE
304Not ModifiedETag cache hit
4xx — 5xx Errors
400Bad Requestinvalid JSON
401Unauthorizedmissing token
403Forbiddenblocked-token
404Not Foundunknown ID
405Method Not Allowedwrong verb
415Unsupported Media Typeno Content-Type
422Validation Failedbad field values
429Too Many Requests>60 / min
500Internal Server Errorunexpected crash
07
Rate Limiting
| X-RateLimit-Limit | Max requests per minute — 60 |
| X-RateLimit-Remaining | Requests left in the current window |
| X-RateLimit-Reset | Seconds until the window resets |
08
Notes
| Seed data | 20 pre-loaded users, IDs 1001–1020. New users auto-increment from 1021. |
| Persistence | In-memory only — resets on server restart. Intentional; clean slate every session. |
| Duplicate email | Returns 422 with a field-level validation message. |
| Pagination headers | X-Pagination-Total X-Pagination-Pages X-Pagination-Page X-Pagination-Limit |
| Replaces | gorest.co.in — same URL structure, compatible with existing Postman collections. |