API reference
every endpoint, explained

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.

{
  "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" }
  ]
}