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.

Access tokens

Your API tokens. A token can make narrower tokens for one job and revoke them, so an app never needs your main token.

The access token object

idstring (uuid)
labelstring
last4string: The last 4 characters of the value.
scopesarray of Scope
rate_limitinteger: Calls a minute.
is_primaryboolean: The account's first token; it cannot be revoked.
expires_atstring, or null (date-time): When the token stops working; null for an older token with no end.
created_atstring (date-time)
made_bystring, or null (uuid): The token that made this one here; revoking that token revokes this one too. null for a token made on the site.

Endpoints

GET/public/v3/access-tokens POST/public/v3/access-tokens GET/public/v3/access-tokens/:id DELETE/public/v3/access-tokens/:id

The access token object

{
  "id": "0190a8e4-0000-7000-8000-000000000001",
  "label": "My app",
  "last4": "Xb3Q",
  "scopes": [
    "users:read",
    "users:write"
  ],
  "rate_limit": 300,
  "is_primary": false,
  "expires_at": "2026-10-31T09:30:00Z",
  "created_at": "2026-10-31T09:30:00Z",
  "made_by": "0190a8e4-0000-7000-8000-000000000001"
}

List your tokens

GET/public/v3/access-tokens

Every token of your account, the primary one first, then the newest. An account has at most 50, so the list is one page. The values are never shown again. Needs a token with access-tokens:read.

Parameters

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/access-tokens?page[size]=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200

{
  "data": [
    {
      "id": "0190a8e4-0000-7000-8000-000000000001",
      "label": "My app",
      "last4": "Xb3Q",
      "scopes": [
        "users:read",
        "users:write"
      ],
      "rate_limit": 300,
      "is_primary": false,
      "expires_at": "2026-10-31T09:30:00Z",
      "created_at": "2026-10-31T09:30:00Z",
      "made_by": "0190a8e4-0000-7000-8000-000000000001"
    }
  ],
  "meta": {
    "has_more": false,
    "next_cursor": null,
    "total": null
  }
}

Make a token

POST/public/v3/access-tokens

The answer holds the value once; only its SHA-256 is kept. The new token gets the scopes you name, each of which the calling token must hold (403 otherwise), the calling token's rate limit, and an end within a year that is not after the calling token's own end (a year from now, or the calling token's end if sooner, when none is sent). It is never the primary token, and revoking the calling token later revokes it too. Needs a token with access-tokens:write.

Parameters

Idempotency-Keyheader, stringoptional: A unique key (a UUID is fine) that makes a POST safe to retry for 24 hours. A retry with the same key, path and body gets the first answer again with Idempotent-Replayed: true and creates nothing; a retry while the first is still running gets 409 conflict with Retry-After: 1. The same key with another request gets 422 idempotency_key_mismatch. Only a 2xx answer is kept, so after an error the retry runs again. An answer over 64 KiB, or one that holds a new token's value, is not kept: its retry gets 409 conflict with the Location of what the first request made.
labelbody, stringrequired: A name to remember the token by; unique among your tokens.
scopesbody, array of Scoperequired
expires_atbody, string (date-time)optional: When the token stops working; within a year, and not after the calling token's own end.

curl -X POST "https://gorest.co.in/public/v3/access-tokens" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label":"CI deploy","scopes":["posts:read","posts:write"]}'

Response 201

{
  "id": "0190a8e4-0000-7000-8000-000000000001",
  "label": "My app",
  "last4": "Xb3Q",
  "scopes": [
    "users:read",
    "users:write"
  ],
  "rate_limit": 300,
  "is_primary": false,
  "expires_at": "2026-10-31T09:30:00Z",
  "created_at": "2026-10-31T09:30:00Z",
  "made_by": "0190a8e4-0000-7000-8000-000000000001",
  "value": "gorest_7nQm2xVb9KpL4sTd8RfW3yHc6ZjN1aGe5uYo0iXkB2hF4D"
}

Get one of your tokens

GET/public/v3/access-tokens/:id

Needs a token with access-tokens:read.

Parameters

idpath, string (uuid)required: A UUID.
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/access-tokens/0190a8e4-0000-7000-8000-000000000001" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 200

{
  "id": "0190a8e4-0000-7000-8000-000000000001",
  "label": "My app",
  "last4": "Xb3Q",
  "scopes": [
    "users:read",
    "users:write"
  ],
  "rate_limit": 300,
  "is_primary": false,
  "expires_at": "2026-10-31T09:30:00Z",
  "created_at": "2026-10-31T09:30:00Z",
  "made_by": "0190a8e4-0000-7000-8000-000000000001"
}

Revoke one of your tokens

DELETE/public/v3/access-tokens/:id

The token stops working at once, and so do the tokens it made, and theirs. A token may revoke itself. The primary token cannot be revoked (409); refresh it on the site instead. Needs a token with access-tokens:write.

Parameters

idpath, string (uuid)required: A UUID.

curl -X DELETE "https://gorest.co.in/public/v3/access-tokens/0190a8e4-0000-7000-8000-000000000001" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 204

(empty body)

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.

API referenceevery endpoint, explained

Access tokens

The access token object

List your tokens

Parameters

Make a token

Parameters

Get one of your tokens

Parameters

Revoke one of your tokens

Parameters

Authentication

Pagination

Rate limits

Errors and status codes

Format and testing

API reference
every endpoint, explained