Skip to content
Go REST

API reference
every endpoint, explained

Parameters, request examples and responses for every v3 resource, made from the OpenAPI spec.

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

This is v3, the current version. The v2 reference or the Swagger UI.

HTTP tools

Tools for learning HTTP and testing clients, in place of httpbin. No token needed; with one, its own rate limit applies.

Endpoints
GET/public/v3/http/status/:codeGET/public/v3/http/delay/:msGET/public/v3/http/echoPOST/public/v3/http/echoPUT/public/v3/http/echoPATCH/public/v3/http/echoDELETE/public/v3/http/echoGET/public/v3/http/headersGET/public/v3/http/ipGET/public/v3/http/uuid

Answer with a status you choose

GET/public/v3/http/status/:code

For testing how a client handles each status. 2xx and 3xx answer an HttpStatus body (204, 205 and 304 none); 4xx and 5xx answer Problem Details with the code requested_status. A 401 has WWW-Authenticate, a 405 Allow and a 429 or 503 Retry-After, as real ones do. A token is optional: with one you also see your own rows.

Parameters

codepath, integerrequired
The status to answer, 200 to 599.
curl "https://gorest.co.in/public/v3/http/status/204"
Response 204
(empty body)

Answer after a wait

GET/public/v3/http/delay/:ms

For testing loading states and timeouts. The wait stops early when the client goes away. When too many waits run at once the answer is 503 with Retry-After. A token is optional: with one you also see your own rows.

Parameters

mspath, integerrequired
How long to wait, 0 to 10,000 milliseconds.
curl "https://gorest.co.in/public/v3/http/delay/1500"
Response 200
{
  "delay_ms": 1500
}

Echo a GET request

GET/public/v3/http/echo

A token is optional: with one you also see your own rows.

curl "https://gorest.co.in/public/v3/http/echo"
Response 200
{
  "method": "GET",
  "path": "/public/v3/http/echo",
  "query": {},
  "headers": {},
  "body": null,
  "body_encoding": null
}

Echo a POST request

POST/public/v3/http/echo

A token is optional: with one you also see your own rows.

curl -X POST "https://gorest.co.in/public/v3/http/echo"
Response 200
{
  "method": "POST",
  "path": "/public/v3/http/echo",
  "query": {},
  "headers": {},
  "body": "{\"name\":\"Asha\"}",
  "body_encoding": "text"
}

Echo a PUT request

PUT/public/v3/http/echo

A token is optional: with one you also see your own rows.

curl -X PUT "https://gorest.co.in/public/v3/http/echo"
Response 200
{
  "method": "PUT",
  "path": "/public/v3/http/echo",
  "query": {},
  "headers": {},
  "body": "{\"name\":\"Asha\"}",
  "body_encoding": "text"
}

Echo a PATCH request

PATCH/public/v3/http/echo

A token is optional: with one you also see your own rows.

curl -X PATCH "https://gorest.co.in/public/v3/http/echo"
Response 200
{
  "method": "PATCH",
  "path": "/public/v3/http/echo",
  "query": {},
  "headers": {},
  "body": "{\"name\":\"Asha\"}",
  "body_encoding": "text"
}

Echo a DELETE request

DELETE/public/v3/http/echo

A token is optional: with one you also see your own rows.

curl -X DELETE "https://gorest.co.in/public/v3/http/echo"
Response 200
{
  "method": "DELETE",
  "path": "/public/v3/http/echo",
  "query": {},
  "headers": {},
  "body": "{\"name\":\"Asha\"}",
  "body_encoding": "text"
}

Show the request headers

GET/public/v3/http/headers

The headers the API received, without Authorization, Cookie and the headers the proxies on the way add. A token is optional: with one you also see your own rows.

curl "https://gorest.co.in/public/v3/http/headers"
Response 200
{
  "headers": {}
}

Show your IP address

GET/public/v3/http/ip

A token is optional: with one you also see your own rows.

curl "https://gorest.co.in/public/v3/http/ip"
Response 200
{
  "ip": "203.0.113.7"
}

Make a UUID

GET/public/v3/http/uuid

A new UUIDv7, which sorts by the time it was made. A token is optional: with one you also see your own rows.

curl "https://gorest.co.in/public/v3/http/uuid"
Response 200
{
  "uuid": "019a3c4e-7b10-7d2a-9c4e-2f1b6a8d0e55"
}

Authentication

Most reads need no token: you see the read only sample data. With a token you also see your own rows. Writes, and the access tokens, my data and change stream calls, need a token with the scope the call names, such as users:write. Make a token on the tokens page after you log in.

Authorization: Bearer YOUR_TOKEN
The only way to send a token in v3. A token never goes in the URL.

No token or a wrong one gives 401 with WWW-Authenticate. A token without the scope gives 403 with error="insufficient_scope". Sample rows (read_only: true) cannot be changed.

Make a token

Pagination

A list answers {"data": [...], "meta": {...}}, 25 items by default. Set page[size] from 1 to 100. For the next page send page[after] with meta.next_cursor; the same link is in the Link header.

meta.has_more
true when there is a next page.
meta.next_cursor
Send it as page[after] for the next page; null on the last one.
meta.total
Only with page[count]=true, or with page[number].
page[number]
Offset paging from 1 to 10,000, in place of page[after].
Link
rel="next", "prev", "first" and, for offset paging, "last" (RFC 8288).

Rate limits

Every answer carries the IETF rate limit fields. A token has its own limit, 300 calls a minute by default (1 to 600, set on the tokens page). With no token, an IP gets 120 calls a minute. Past the limit you get 429 with Retry-After.

RateLimit-Policy
The limit and its window, for example "token";q=300;w=60.
RateLimit
Calls left and the seconds until the window resets.
Retry-After
On a 429: the seconds to wait.

Errors and status codes

200 OK
The item or the list is in the body.
201 Created
The new item is in the body, and Location has its URL.
204 No Content
A delete worked. The body is empty.
304 Not Modified
Your copy (If-None-Match with the ETag) is still good.
400 Bad Request
A parameter is wrong, unknown or out of range.
401 Unauthorized
No token, or it is wrong, expired or revoked.
403 Forbidden
The token lacks the scope, or the row is sample data.
404 Not Found
No such item, or you cannot see it.
409 Conflict
A duplicate, or the same Idempotency-Key is busy.
412 Precondition Failed
If-Match did not match: someone changed the item.
422 Unprocessable
A field failed a check. errors has a pointer and a code for each.
429 Too Many Requests
The rate limit is used up; wait Retry-After seconds.
500 Server Error
A fault on our side. Send the request_id when you report it.
A 422 body 422Every error code
{
  "type": "https://www.gorest.co.in/docs/api/errors#validation_failed",
  "title": "Unprocessable Content",
  "status": 422,
  "code": "validation_failed",
  "detail": "Some fields are not valid.",
  "instance": "/public/v3/users",
  "request_id": "0190a8e4-0000-7000-8000-0000000000aa",
  "errors": [
    { "pointer": "/email", "code": "taken", "detail": "has already been taken" }
  ]
}

Format and testing

/http/status/503
Answers with that status, with the headers a real one carries. Any code from 200 to 599.
/http/delay/1500
Waits that many milliseconds, up to 10,000, then answers.
ETag and If-Match
Send If-Match on PATCH or DELETE so you never overwrite a newer change (412 if it changed).
Idempotency-Key
A header on POST that makes a retry safe: the same answer for 24 hours.
fields, include, sort
fields[users]=id,name returns fewer fields; include=user embeds the related item; sort=-created_at orders a list.

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