GET /api
This endpoint provides documentation detailing all of the available API endpoints.
GET /api/topics
This endpoint provides a list of all topics.
Sample output
{
"topics": [
{ "slug": "football", "description": "Footie!" },
{ "slug": "cats", "description": "Domestic feline creatures." },
]
}
GET /api/users
This endpoint provides a list of all users.
Sample output
{
"users": [
{"username": "user123", "name": "Arthur Smithee", "avatar_url": "https://openclipart.org/image/800px/250860"},
{"username": "user456", "name": "Jack Jones", "avatar_url": "https://openclipart.org/image/800px/250860"},
]
}
GET /api/users/:username
This endpoint returns details of an inidivual user, specified by their
username.
Sample output
{
"user": {
"username": "user123",
"name": "Arthur Smithee",
"avatar_url": "https://openclipart.org/image/800px/250860"
}
}
GET /api/articles
This endpoint provides a list of all articles.
Queries
This endpoint takes the following query options:
-
sort_byany column (defaults tocreated_at) -
orderbyasc(ascending) ordesc(descending) (defaults todesc) -
topicto filter by a topic, specified by itsslug(defaults to all topics)
Sample output
{
"articles": [
{
"author": "weegembump",
"title": "Sunday league football",
"article_id": 23
"topic": "football",
"created_at": "2020-03-22 14:25:00",
"votes": 5,
"article_img_url": "https://images.pexels.com/photos/774321/pexels-photo-774321.jpeg?w=700&h=700"
"comment_count": 3
},
{
"author": "weegembump",
"title": "Seafood substitutions are increasing",
"article_id": 33
"topic": "cooking",
"created_at": "2018-05-30T15:59:13.341Z",
"votes": 0,
"article_img_url": "https://images.pexels.com/photos/1267320/pexels-photo-1267320.jpeg?w=700&h=700"
"comment_count": 6
}
]
}
GET /api/articles/:article_id
This endpoint returns details of an inidivual article, specified by
its article_id.
Sample output
{
"article": {
"author": "weegembump",
"title": "Brian Clough - In The Top One",
"article_id": 12345,
"body": "Brian Clough was almost certainly the greatest English manager not to manage the national side.
His success at Derby County, leading to them becoming champions of England, was followed by...",
"topic": "football",
"created_at": "2025-06-04T15:59:13.341Z",
"votes": 72,
"article_img_url": "https://upload.wikimedia.org/wikipedia/commons/0/0b/Clough_and_Taylor_Statue_Derby.JPG",
"comment_count": 55
}
}
GET /api/articles/:article_id/comments
This endpoint returns an array of all comments on an inidivual
article, specified by its article_id, newest first.
Sample output
{
"comments": [
{
"comment_id": 45678,
"votes": 1972,
"created_at": "2025-06-04T21:59:13.341Z",
"author": "weegembump",
"body": "This article focuses too much on his managerial days and not Clough's earlier life as a child and player",
"article_id": 12345
},
{
"comment_id": 45677,
"votes": 0,
"created_at": "2025-06-04T20:59:13.341Z",
"author": "jessjelly",
"body": "A great article, even though I don't like football much!",
"article_id": 12345
},
]
}
POST /api/topics
This endpoint adds a new topic and on success, returns the new topic.
Input format
{
"slug": "rugby",
"description": "A gentleman's sport"
}
Sample output
{ "topic": { "slug": "rugby", "description": "A gentleman's sport" } }
POST /api/articles
This endpoint adds a new article and on success, returns the new article.
Input format
{
"author": "weegembump",
"title": "Brian Clough - In The Top One",
"body": "Brian Clough was almost certainly the greatest English manager not to manage the national side.
His success at Derby County, leading to them becoming champions of England, was followed by...",
"topic": "football",
"article_img_url": "https://upload.wikimedia.org/wikipedia/commons/0/0b/Clough_and_Taylor_Statue_Derby.JPG"
}
Sample output
{
"newArticle": {
"author": "weegembump",
"title": "Brian Clough - In The Top One",
"article_id": 12345,
"body": "Brian Clough was almost certainly the greatest English manager not to manage the national side.
His success at Derby County, leading to them becoming champions of England, was followed by...",
"topic": "football",
"created_at": "2025-06-04T15:59:13.341Z",
"votes": 0,
"article_img_url": "https://upload.wikimedia.org/wikipedia/commons/0/0b/Clough_and_Taylor_Statue_Derby.JPG",
"comment_count": 0
}
}
POST /api/articles/:article_id/comments
This endpoint post a new comment on an article, specified by its
article_id.
Input format
{
"author": "jessjelly",
"body": "More articles like this please!"
}
Sample output
{
"newComment": {
"comment_id": 45680,
"votes": 0,
"created_at": "2025-06-04T22:59:13.341Z",
"author": "jessjelly",
"body": "More articles like this please!",
"article_id": 12345
}
}
PATCH /api/articles/:article_id
This endpoint adds a number of votes (positive or negative) to an
existing article, specified by its article_id, and
outputs the updated article.
Input format
{ inc_votes : 1 }
Sample output
{
"article": {
"author": "weegembump",
"title": "Brian Clough - In The Top One",
"article_id": 12345,
"body": "Brian Clough was almost certainly the greatest English manager not to manage the national side.
His success at Derby County, leading to them becoming champions of England, was followed by...",
"topic": "football",
"created_at": "2025-06-04T15:59:13.341Z",
"votes": 101,
"article_img_url": "https://upload.wikimedia.org/wikipedia/commons/0/0b/Clough_and_Taylor_Statue_Derby.JPG",
}
}
PATCH /api/comments/:comment_id
This endpoint adds a number of votes (positive or negative) to an
existing comment, specified by its comment_id, and
outputs the updated comment.
Input format
{ inc_votes : -1 }
Sample output
{
"comment": {
"comment_id": 45680,
"votes": -1,
"created_at": "2025-06-04T22:59:13.341Z",
"author": "jessjelly",
"body": "More articles like this please!",
"article_id": 12345
}
}
DELETE /api/comments/:comment_id
This endpoint deletes an existing comment, specified by its
comment_id, and returns no content (status code: 204).