01Endpoints
| GET | /public/v2/users | public | List all users — paginated & filterable |
| 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 |
02Authentication
GET requests are open — no token needed. Hit them straight from browser, Postman, or any test tool.
POST, PUT, PATCH, DELETE require an Authorization: Bearer <token> header. Any non-empty string works — demo-token, abc123, your name, anything.
⚠ Exception: blocked-token deliberately returns 403 Forbidden — useful for testing error-handling flows.
03User Schema
{
"id": 1001,
"name": "Aarav Sharma",
"email": "aarav.sharma@example.com",
"gender": "male" // "male" | "female"
"status": "active" // "active" | "inactive"
}
"id": 1001,
"name": "Aarav Sharma",
"email": "aarav.sharma@example.com",
"gender": "male" // "male" | "female"
"status": "active" // "active" | "inactive"
}
04Query 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 |
05Response Format — JSON & XML
All endpoints return JSON by default. Request XML using either method:
Option 1 — URL suffix: append .xml to any endpoint URL.
Option 2 — Accept header: send Accept: application/xml in your request.
curl https://gorest.in/public/v2/users.xml
curl https://gorest.in/public/v2/users/1001.xml
curl https://gorest.in/public/v2/users -H "Accept: application/xml"
<?xml version="1.0" encoding="UTF-8"?> <users> <user> <id>1001</id> <name>Aarav Sharma</name> <email>aarav.sharma@example.com</email> <gender>male</gender> <status>active</status> </user> </users>
06cURL 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"
07HTTP 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
08Rate Limiting
| X-RateLimit-Limit | Max requests allowed per minute — 60 |
| X-RateLimit-Remaining | Requests remaining in the current window |
| X-RateLimit-Reset | Seconds until the window resets |
09Notes
| Seed data | 20 pre-loaded users, IDs 1001–1020. New users auto-increment from 1021. |
| Persistence | In-memory only — resets on server restart. Clean slate every session. |
| Duplicate email | Returns 422 with a field-level validation error message. |
| Pagination headers | X-Pagination-Total X-Pagination-Pages X-Pagination-Page X-Pagination-Limit |
| XML support | Append .xml to any URL or send Accept: application/xml header. |
| Replaces | gorest.co.in — same URL structure, existing Postman collections work as-is. |
10Try It — Live Playground
Any non-empty token is accepted. Use
blocked-token to trigger 403.
Response
Hit Send to see the response