Skip to content
Go REST

API reference
every endpoint, explained

Parameters, request examples and responses for users, posts, comments and todos.

Base URLhttps://gorest.co.in/public/v2

Users

A user has posts and todos. Reading users needs no token. Creating, updating and deleting do, and those records are visible only to your token.

The user object

idinteger
Unique identifier.
namestring
Full name. Up to 200 characters.
emailstring
Email address. Must be valid and unique.
genderenum
male or female
statusenum
active or inactive
Endpoints
GET/public/v2/usersGET/public/v2/users/:idPOST/public/v2/usersPATCH/public/v2/users/:idDELETE/public/v2/users/:id
The user object
{
  "id": 7012,
  "name": "Avani Iyer",
  "email": "avani.iyer@example.com",
  "gender": "female",
  "status": "active"
}

List users

GET/public/v2/users

Returns a page of users, the most recently changed first. Any field can be a filter.

Query parameters

pageintegeroptional
Page number. Starts at 1.
per_pageintegeroptional
Results per page, 1 to 100. Any other value gives 10.
idintegeroptional
Exact id.
namestringoptional
Part of the name. Not case sensitive.
emailstringoptional
Part of the email. Not case sensitive.
gendermale | femaleoptional
Exact match.
statusactive | inactiveoptional
Exact match.

The pagination headers come with the list. See Pagination below.

curl "https://gorest.co.in/public/v2/users?page=1&per_page=10"
Response 200
[
  {
    "id": 7012,
    "name": "Avani Iyer",
    "email": "avani.iyer@example.com",
    "gender": "female",
    "status": "active"
  }
]

Get a user

GET/public/v2/users/:id

Returns one user. A wrong id gives 404.

Path parameters

idintegerrequired
The id of the record.
curl "https://gorest.co.in/public/v2/users/7012"
Response 200
{
  "id": 7012,
  "name": "Avani Iyer",
  "email": "avani.iyer@example.com",
  "gender": "female",
  "status": "active"
}

Create a user

POST/public/v2/users

Needs a token. Returns 201 with the new user and a Location header, or 422 with a list of field errors.

Body parameters

namestringrequired
Full name. Up to 200 characters.
emailstringrequired
Valid email, up to 200 characters. A taken email gives 422.
gendermale | femalerequired
The gender.
statusactive | inactiverequired
The status.

Only your token can see the new record.

curl -X POST "https://gorest.co.in/public/v2/users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Avani Iyer","email":"avani.iyer@example.com","gender":"female","status":"active"}'
Response 201
{
  "id": 7012,
  "name": "Avani Iyer",
  "email": "avani.iyer@example.com",
  "gender": "female",
  "status": "active"
}

Update a user

PATCH/public/v2/users/:id

Needs a token. Changes only the fields you send and returns the user. PUT does the same as PATCH. A record you cannot see gives 404.

Body parameters

namestringoptional
Full name. Up to 200 characters.
emailstringoptional
Valid email, up to 200 characters. A taken email gives 422.
gendermale | femaleoptional
The gender.
statusactive | inactiveoptional
The status.
curl -X PATCH "https://gorest.co.in/public/v2/users/7012" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}'
Response 200
{
  "id": 7012,
  "name": "Avani Iyer",
  "email": "avani.iyer@example.com",
  "gender": "female",
  "status": "inactive"
}

Delete a user

DELETE/public/v2/users/:id

Needs a token. Returns 204 with an empty body.

Path parameters

idintegerrequired
The id of the record.

If the table has fewer than 100 seeded records, the delete is refused with 422.

curl -X DELETE "https://gorest.co.in/public/v2/users/7012" \
  -H "Authorization: Bearer YOUR_TOKEN"
Response 204
(empty body)

Authentication

Reading needs no token. Writing (POST, PATCH, PUT, DELETE) needs one. Make a token on the tokens page after you log in, and send it in one of two ways.

Authorization: Bearer YOUR_TOKEN
A request header. This is the better way.
?access-token=YOUR_TOKEN
A query parameter, for quick tests in the browser.

A write without a token gives 401. A token that is wrong gives 401 "Invalid token", and an expired one gives 401 "Token expired". A token can only see the seeded records and its own.

Make a token

Pagination

Lists give 10 records a page. Use page and per_page (1 to 100) to change that. Details come in the response headers.

X-Pagination-Total
Total records that match.
X-Pagination-Pages
Total pages.
X-Pagination-Page
The current page.
X-Pagination-Limit
Records on a page.
X-Links-Previous
Full URL of the previous page. Empty on page 1.
X-Links-Current
Full URL of this page.
X-Links-Next
Full URL of the next page. Empty on the last page.

Rate limits

Each token can send 300 requests a minute by default. You can set it from 1 to 600 on the tokens page. Reads without a token have no limit. Calls with a token carry these headers. Past the limit you get 429 "Too many requests".

X-RateLimit-Limit
Requests a minute allowed for this token.
X-RateLimit-Remaining
Requests left now.
X-RateLimit-Reset
Seconds until you get more requests.

Errors and status codes

200 OK
The request worked. The record or list is in the body.
201 Created
A record was made. The Location header has its URL.
204 No Content
A delete worked. The body is empty.
304 Not Modified
Your cached copy (If-None-Match with the ETag) is still good.
400 Bad Request
A parameter is not valid text.
401 Unauthorized
The token is missing, wrong or expired.
404 Not Found
No such record, or it belongs to another token.
422 Unprocessable
A field failed a check. The body is a list of field and message.
429 Too Many Requests
The rate limit is used up.
500 Server Error
A fault on our side.
A 422 body 422
[
  { "field": "email", "message": "has already been taken" }
]

Format and testing

?delay=1500
On a GET, waits that many milliseconds first. The most is 5000. The answer has X-Simulated-Delay-Ms.
?force_status=503
Answers with that code. Allowed: 400, 401, 403, 404, 405, 415, 422, 429, 500 and 503.
.json or .xml
Add it to the path, or set the Accept header, to choose JSON or XML. JSON is the default.

Want to try a call now? Open the REST console.