JSONPlaceholder API

Appearance

API Reference ​

Complete reference for all JSONPlaceholder.dev API endpoints. This documentation matches the comprehensive Postman collection structure.

🌐 Public API Available

Ready to use! You can test all these endpoints immediately using our public API at https://api.jsonplaceholder.dev - no setup required!

Base URL ​

bash
https://api.jsonplaceholder.dev
bash
http://localhost:3000

Authentication ​

No authentication required. This is a public testing API.

Response Format ​

All responses are in JSON format. Success responses return the requested data, while error responses include an error message.

json
// Success Response Example
{
  "id": 1,
  "name": "Leanne Graham",
  "username": "Bret",
  "email": "[email protected]"
}

// Error Response Example
{
  "error": "Not Found",
  "message": "Resource with ID 999 not found"
}

HTTP Status Codes ​

  • 200 OK - Successful GET, PUT, PATCH
  • 201 Created - Successful POST
  • 204 No Content - Successful DELETE
  • 400 Bad Request - Invalid request data
  • 404 Not Found - Resource not found
  • 500 Internal Server Error - Server error

Posts ​

Manage blog posts with full CRUD operations.

Get All Posts ​

http
GET /posts

Response: Array of all posts (100 items)

Get Posts by User ​

http
GET /posts?userId={userId}

Parameters:

  • userId (number) - Filter posts by user ID

Response: Array of posts by the specified user

Get Single Post ​

http
GET /posts/{id}

Parameters:

  • id (number) - Post ID

Response: Single post object

Get Post Comments ​

http
GET /posts/{id}/comments

Parameters:

  • id (number) - Post ID

Response: Array of comments for the specified post

Create Post ​

http
POST /posts
Content-Type: application/json

Request Body:

json
{
  "userId": 1,
  "title": "New Post Title",
  "body": "Post content goes here"
}

Response: Created post with assigned ID

Update Post (Full Replace) ​

http
PUT /posts/{id}
Content-Type: application/json

Parameters:

  • id (number) - Post ID

Request Body:

json
{
  "id": 1,
  "userId": 1,
  "title": "Updated Post Title",
  "body": "Updated post content"
}

Response: Updated post object

Update Post (Partial) ​

http
PATCH /posts/{id}
Content-Type: application/json

Parameters:

  • id (number) - Post ID

Request Body:

json
{
  "title": "New Title Only"
}

Response: Updated post object

Delete Post ​

http
DELETE /posts/{id}

Parameters:

  • id (number) - Post ID

Response: Empty response with 204 status

Users ​

Manage user accounts with complete profile information.

Get All Users ​

http
GET /users

Response: Array of all users (10 items)

Get Single User ​

http
GET /users/{id}

Parameters:

  • id (number) - User ID

Response: Single user object with full profile

Get User Posts ​

http
GET /users/{id}/posts

Parameters:

  • id (number) - User ID

Response: Array of posts by the specified user

Get User Albums ​

http
GET /users/{id}/albums

Parameters:

  • id (number) - User ID

Response: Array of albums by the specified user

Get User Todos ​

http
GET /users/{id}/todos

Parameters:

  • id (number) - User ID

Response: Array of todos by the specified user

Create User ​

http
POST /users
Content-Type: application/json

Request Body:

json
{
  "name": "John Doe",
  "username": "johndoe",
  "email": "[email protected]",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "zipcode": "10001"
  },
  "phone": "1-555-123-4567",
  "website": "johndoe.com"
}

Response: Created user with assigned ID

Update User (Full Replace) ​

http
PUT /users/{id}
Content-Type: application/json

Parameters:

  • id (number) - User ID

Request Body: Complete user object (same as POST)

Response: Updated user object

Update User (Partial) ​

http
PATCH /users/{id}
Content-Type: application/json

Parameters:

  • id (number) - User ID

Request Body:

json
{
  "email": "[email protected]"
}

Response: Updated user object

Delete User ​

http
DELETE /users/{id}

Parameters:

  • id (number) - User ID

Response: Empty response with 204 status

Comments ​

Manage post comments with full CRUD operations.

Get All Comments ​

http
GET /comments

Response: Array of all comments (500 items)

Get Comments by Post (Query) ​

http
GET /comments?postId={postId}

Parameters:

  • postId (number) - Filter comments by post ID

Response: Array of comments for the specified post

Get Comments by Post (Path) ​

http
GET /posts/{postId}/comments

Parameters:

  • postId (number) - Post ID

Response: Array of comments for the specified post

Get Single Comment ​

http
GET /comments/{id}

Parameters:

  • id (number) - Comment ID

Response: Single comment object

Create Comment ​

http
POST /comments
Content-Type: application/json

Request Body:

json
{
  "postId": 1,
  "name": "Great post!",
  "email": "[email protected]",
  "body": "Thanks for sharing this information!"
}

Response: Created comment with assigned ID

Update Comment (Full Replace) ​

http
PUT /comments/{id}
Content-Type: application/json

Parameters:

  • id (number) - Comment ID

Request Body: Complete comment object

Response: Updated comment object

Update Comment (Partial) ​

http
PATCH /comments/{id}
Content-Type: application/json

Parameters:

  • id (number) - Comment ID

Request Body:

json
{
  "body": "Updated comment text"
}

Response: Updated comment object

Delete Comment ​

http
DELETE /comments/{id}

Parameters:

  • id (number) - Comment ID

Response: Empty response with 204 status

Albums ​

Manage photo albums with full CRUD operations.

Get All Albums ​

http
GET /albums

Response: Array of all albums (100 items)

Get Albums by User ​

http
GET /albums?userId={userId}

Parameters:

  • userId (number) - Filter albums by user ID

Response: Array of albums for the specified user

Get Single Album ​

http
GET /albums/{id}

Parameters:

  • id (number) - Album ID

Response: Single album object

Get Album Photos ​

http
GET /albums/{id}/photos

Parameters:

  • id (number) - Album ID

Response: Array of photos in the specified album

Create Album ​

http
POST /albums
Content-Type: application/json

Request Body:

json
{
  "userId": 1,
  "title": "My Vacation Photos"
}

Response: Created album with assigned ID

Update Album (Full Replace) ​

http
PUT /albums/{id}
Content-Type: application/json

Parameters:

  • id (number) - Album ID

Request Body: Complete album object

Response: Updated album object

Update Album (Partial) ​

http
PATCH /albums/{id}
Content-Type: application/json

Parameters:

  • id (number) - Album ID

Request Body:

json
{
  "title": "Updated Album Title"
}

Response: Updated album object

Delete Album ​

http
DELETE /albums/{id}

Parameters:

  • id (number) - Album ID

Response: Empty response with 204 status

Photos ​

Manage photos with full CRUD operations.

Get All Photos ​

http
GET /photos

Response: Array of all photos (5000 items) - Note: This is a large response

Get Photos by Album (Query) ​

http
GET /photos?albumId={albumId}

Parameters:

  • albumId (number) - Filter photos by album ID

Response: Array of photos for the specified album

Get Photos by Album (Path) ​

http
GET /albums/{albumId}/photos

Parameters:

  • albumId (number) - Album ID

Response: Array of photos in the specified album

Get Single Photo ​

http
GET /photos/{id}

Parameters:

  • id (number) - Photo ID

Response: Single photo object

Create Photo ​

http
POST /photos
Content-Type: application/json

Request Body:

json
{
  "albumId": 1,
  "title": "Beautiful sunset",
  "url": "https://via.placeholder.com/600/sunset",
  "thumbnailUrl": "https://via.placeholder.com/150/sunset"
}

Response: Created photo with assigned ID

Update Photo (Full Replace) ​

http
PUT /photos/{id}
Content-Type: application/json

Parameters:

  • id (number) - Photo ID

Request Body: Complete photo object

Response: Updated photo object

Update Photo (Partial) ​

http
PATCH /photos/{id}
Content-Type: application/json

Parameters:

  • id (number) - Photo ID

Request Body:

json
{
  "title": "New Photo Title"
}

Response: Updated photo object

Delete Photo ​

http
DELETE /photos/{id}

Parameters:

  • id (number) - Photo ID

Response: Empty response with 204 status

Todos ​

Manage todo items with full CRUD operations.

Get All Todos ​

http
GET /todos

Response: Array of all todos (200 items)

Get Todos by User ​

http
GET /todos?userId={userId}

Parameters:

  • userId (number) - Filter todos by user ID

Response: Array of todos for the specified user

Get Single Todo ​

http
GET /todos/{id}

Parameters:

  • id (number) - Todo ID

Response: Single todo object

Create Todo ​

http
POST /todos
Content-Type: application/json

Request Body:

json
{
  "userId": 1,
  "title": "Learn API testing",
  "completed": false
}

Response: Created todo with assigned ID

Update Todo (Full Replace) ​

http
PUT /todos/{id}
Content-Type: application/json

Parameters:

  • id (number) - Todo ID

Request Body: Complete todo object

Response: Updated todo object

Update Todo (Partial) ​

http
PATCH /todos/{id}
Content-Type: application/json

Parameters:

  • id (number) - Todo ID

Request Body:

json
{
  "completed": true
}

Response: Updated todo object

Delete Todo ​

http
DELETE /todos/{id}

Parameters:

  • id (number) - Todo ID

Response: Empty response with 204 status

Admin ​

Administrative endpoints for data management.

Reset All Data ​

http
POST /reset

Requirements:

  • Server must be running with ENABLE_UPDATES=1
  • Only works in live mode, not read-only mode

Response:

json
{
  "message": "Data reset successful",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "cleared": {
    "cache": true,
    "data": true
  }
}

Error Response (Read-only mode):

json
{
  "error": "Forbidden",
  "message": "Reset endpoint is only available when ENABLE_UPDATES=1"
}

Data Models ​

User Model ​

json
{
  "id": 1,
  "name": "Leanne Graham",
  "username": "Bret",
  "email": "[email protected]",
  "address": {
    "street": "Kulas Light",
    "suite": "Apt. 556",
    "city": "Gwenborough",
    "zipcode": "92998-3874",
    "geo": {
      "lat": "-37.3159",
      "lng": "81.1496"
    }
  },
  "phone": "1-770-736-8031",
  "website": "hildegard.org",
  "company": {
    "name": "Romaguera-Crona",
    "catchPhrase": "Multi-layered client-server neural-net",
    "bs": "harness real-time e-markets"
  }
}

Post Model ​

json
{
  "userId": 1,
  "id": 1,
  "title": "sunt aut facere repellat provident occaecati excepturi optio reprehenderit",
  "body": "quia et suscipit\nsuscipit recusandae consequuntur expedita et cum\nreprehenderit molestiae ut ut quas totam\nnostrum rerum est autem sunt rem eveniet architecto"
}

Comment Model ​

json
{
  "postId": 1,
  "id": 1,
  "name": "id labore ex et quam laborum",
  "email": "[email protected]",
  "body": "laudantium enim quasi est quidem magnam voluptate ipsam eos\ntempora quo necessitatibus\ndolor quam autem quasi\nreiciendis et nam sapiente accusantium"
}

Album Model ​

json
{
  "userId": 1,
  "id": 1,
  "title": "quidem molestiae enim"
}

Photo Model ​

json
{
  "albumId": 1,
  "id": 1,
  "title": "accusamus beatae ad facilis cum similique qui sunt",
  "url": "https://via.placeholder.com/600/92c952",
  "thumbnailUrl": "https://via.placeholder.com/150/92c952"
}

Todo Model ​

json
{
  "userId": 1,
  "id": 1,
  "title": "delectus aut autem",
  "completed": false
}

Rate Limiting ​

Currently, there are no rate limits imposed. However, for performance testing with tools like autocannon, consider:

  • Use DISABLE_CORS=1 for maximum throughput
  • Enable caching with ENABLE_CACHE=1
  • Use specific endpoints rather than fetching all 5000 photos

Error Handling ​

All endpoints may return these common errors:

  • 404 Not Found - Resource with specified ID doesn't exist
  • 400 Bad Request - Invalid JSON or missing required fields
  • 500 Internal Server Error - Unexpected server error

When using the reset endpoint:

  • 403 Forbidden - Server running in read-only mode (ENABLE_UPDATES=0)

Postman Collection ​

Import the complete Postman collection from collections/JSONPlaceholder.postman_collection.json to test all these endpoints with pre-configured requests and sample data.

The collection includes:

  • All CRUD operations for every resource
  • Query parameter examples
  • Sample request bodies
  • Proper error handling examples
  • Admin reset functionality

Fast Fake REST API powered by Bun + Elysia.js | Documentation site source: github.com/ckissi/jsonplaceholder

Copyright © 2025 JSONPlaceholder