API reference
every endpoint, explained

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

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

Todos

A todo is a task that belongs to a user. Reading todos needs no token. Creating, updating and deleting do, and those records are visible only to your token. The due date is shown in India time (+05:30).

The todo object

idinteger: Unique identifier.
user_idinteger: The id of the user who owns the todo.
titlestring: Up to 200 characters.
due_ontimestamp: When the todo is due, or null.
statusenum: pending or completed

Endpoints

GET/public/v2/todos GET/public/v2/todos/:id POST/public/v2/todos PATCH/public/v2/todos/:id DELETE/public/v2/todos/:id GET/public/v2/users/:id/todos POST/public/v2/users/:id/todos

The todo object

{
  "id": 880,
  "user_id": 7012,
  "title": "Book the annual service",
  "due_on": "2026-11-20T00:00:00.000+05:30",
  "status": "pending"
}

List todos

GET/public/v2/todos

Returns a page of todos, 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.
user_idintegeroptional: Todos of this user.
titlestringoptional: Part of the title. Not case sensitive.
due_ondateoptional: Todos due on this day, as 2026-11-20.
statuspending | completedoptional: Exact match.

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

curl "https://gorest.co.in/public/v2/todos?page=1&per_page=10"

Response 200

[
  {
    "id": 880,
    "user_id": 7012,
    "title": "Book the annual service",
    "due_on": "2026-11-20T00:00:00.000+05:30",
    "status": "pending"
  }
]

Get a todo

GET/public/v2/todos/:id

Returns one todo. A wrong id gives 404.

Path parameters

idintegerrequired: The id of the record.

curl "https://gorest.co.in/public/v2/todos/880"

Response 200

{
  "id": 880,
  "user_id": 7012,
  "title": "Book the annual service",
  "due_on": "2026-11-20T00:00:00.000+05:30",
  "status": "pending"
}

Create a todo

POST/public/v2/todos

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

Body parameters

user_idintegerrequired: The id of an existing user.
titlestringrequired: Up to 200 characters.
due_ontimestampoptional: A date such as 2026-11-20, or with a time. Without a zone it is India time. Not valid means null.
statuspending | completedrequired: The status.

Only your token can see the new record.

curl -X POST "https://gorest.co.in/public/v2/todos" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id":7012,"title":"Book the annual service","due_on":"2026-11-20T00:00:00.000+05:30","status":"pending"}'

Response 201

{
  "id": 880,
  "user_id": 7012,
  "title": "Book the annual service",
  "due_on": "2026-11-20T00:00:00.000+05:30",
  "status": "pending"
}

Update a todo

PATCH/public/v2/todos/:id

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

Body parameters

user_idintegeroptional: The id of an existing user.
titlestringoptional: Up to 200 characters.
due_ontimestampoptional: A date such as 2026-11-20, or with a time. Without a zone it is India time. Not valid means null.
statuspending | completedoptional: The status.

curl -X PATCH "https://gorest.co.in/public/v2/todos/880" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status":"completed"}'

Response 200

{
  "id": 880,
  "user_id": 7012,
  "title": "Book the annual service",
  "due_on": "2026-11-20T00:00:00.000+05:30",
  "status": "completed"
}

Delete a todo

DELETE/public/v2/todos/: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/todos/880" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response 204

(empty body)

List the todos of a user

GET/public/v2/users/:id/todos

The same as the list above with user_id set from the path. Paging and the other filters work too.

Path parameters

idintegerrequired: The id of the user.

curl "https://gorest.co.in/public/v2/users/7012/todos"

Response 200

[
  {
    "id": 880,
    "user_id": 7012,
    "title": "Book the annual service",
    "due_on": "2026-11-20T00:00:00.000+05:30",
    "status": "pending"
  }
]

Create a todo for a user

POST/public/v2/users/:id/todos

Needs a token. The user id comes from the path, even if the body has another one. A missing user gives 422 with "must exist".

Body parameters

titlestringrequired: Up to 200 characters.
due_ontimestampoptional: Optional due date.
statuspending | completedrequired: The status.

curl -X POST "https://gorest.co.in/public/v2/users/7012/todos" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Book the annual service","due_on":"2026-11-20","status":"pending"}'

Response 201

{
  "id": 880,
  "user_id": 7012,
  "title": "Book the annual service",
  "due_on": "2026-11-20T00:00:00.000+05:30",
  "status": "pending"
}

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.

API referenceevery endpoint, explained

Todos

The todo object

List todos

Query parameters

Get a todo

Path parameters

Create a todo

Body parameters

Update a todo

Body parameters

Delete a todo

Path parameters

List the todos of a user

Path parameters

Create a todo for a user

Body parameters

Authentication

Pagination

Rate limits

Errors and status codes

Format and testing

API reference
every endpoint, explained