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.

Countries

An ISO 3166-1 country.

The countrie object

codestring
ISO 3166-1 alpha-2.
alpha3string
numeric_codestring
namestring
regionAfrica | Americas | Asia | Europe | Oceania
The UN M49 continent; null for Antarctica.
calling_codestring, or null
The E.164 country calling code; null where there is none.
currency_codestring, or null
The currency in use; null where there is none.
currencyCurrency | null
Endpoints
GET/public/v3/countriesGET/public/v3/countries/:code
The countrie object
{
  "code": "IN",
  "alpha3": "IND",
  "numeric_code": "356",
  "name": "India",
  "region": "Africa",
  "calling_code": "+91",
  "currency_code": "INR"
}

List countries

GET/public/v3/countries

Open to anyone; no token needed.

Parameters

page[size]query, integeroptional
Items on one page.
page[after]query, stringoptional
The cursor of the next page, from meta.next_cursor or the Link header. Treat it as opaque; it works only with the same query.
page[number]query, integeroptional
Offset paging, 1 based, at most 10,000. Cannot be sent with page[after]. Pages can shift while you write.
page[count]query, booleanoptional
true adds meta.total to a cursor page (it costs a count).
searchquery, stringoptional
Case-insensitive text search over the resource's text fields.
filterquery, objectoptional
filter[region]=Asia,Europe (any of the UN M49 continents), filter[currency_code]=INR (either case). search matches the codes and the name.
sortquery, name | -name | code | -codeoptional
One field; a leading - sorts descending. Default name.
fieldsquery, objectoptional
fields[countries]=name,currency_code returns only those fields; code is always there.
includequery, currencyoptional
currency adds the currency of each item.
If-None-Matchheader, stringoptional
An ETag from an earlier answer; an unchanged item answers 304 with no body.
curl -g "https://gorest.co.in/public/v3/countries?page[size]=10"
Response 200
{
  "data": [
    {
      "code": "IN",
      "alpha3": "IND",
      "numeric_code": "356",
      "name": "India",
      "region": "Africa",
      "calling_code": "+91",
      "currency_code": "INR"
    }
  ],
  "meta": {
    "has_more": false,
    "next_cursor": null,
    "total": null
  }
}

Get a country

GET/public/v3/countries/:code

Open to anyone; no token needed.

Parameters

codepath, stringrequired
The ISO code, in either case: IN.
fieldsquery, objectoptional
fields[countries]=name,currency_code returns only those fields; code is always there.
includequery, currencyoptional
currency adds the currency of each item.
If-None-Matchheader, stringoptional
An ETag from an earlier answer; an unchanged item answers 304 with no body.
curl "https://gorest.co.in/public/v3/countries/IN"
Response 200
{
  "code": "IN",
  "alpha3": "IND",
  "numeric_code": "356",
  "name": "India",
  "region": "Africa",
  "calling_code": "+91",
  "currency_code": "INR"
}

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.