Endpoints

Endpoint Details

Authorization and User Management Endpoints

The following endpoints allow you to register a new user, and log in and out of the server.

/auth/register: Register a New User

Use this endpoint to create a new user account by providing a unique email address and a password. Upon successful registration, the user is created in the database and a success response is returned.

Endpoint Details

  • Method: POST

  • URL: /auth/register

Request Body

The request body should be a JSON object containing the user’s username (a valid email address) and password.

Field Type Description Required Example
username string The user’s email address which serves as their unique username. Yes user@example.com
password string The user’s password. It will be hashed before being stored. Yes SecurePassword123!

Example Request

1
2
3
4

{
  "username": "user@example.com",
  "password": "SecurePassword123!"
}

Success Response

The server returns a 201 Created status code upon successful registration. The response body contains the details of the newly created user account.

  • Status Code: 201 Created

  • Body: application/json

Example Success Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "username": "user@example.com",
  "created_at": "2023-08-08T10:00:00Z"
}

Error Responses

This endpoint may return the following error codes:

Status Code Description Example Body
400 Bad Request The request body is malformed, or required fields (username, password) are missing or invalid. Invalid request payload or Username and password are required
409 Conflict A user account with the provided username (email) already exists. Username 'user@example.com' already exists
500 Internal Server Error An unexpected error occurred on the server (e.g., database connection issues, failure to hash password). Failed to register user

/auth/login: Log In

Use this endpoint to log in a user. Upon successful login, the user receives a JWT token, used for accessing protected endpoints.

Endpoint Details

  • Method: POST

  • URL: /auth/login

Request Body

The request body should be a JSON object containing the registered user’s username (a valid email address) and password.

Field Type Description Required Example
username string The registered user’s username (email address). Yes user@example.com
password string The registered user’s password. Yes SecurePassword123!

Example Request

1
2
3
4

{
  "username": "user@example.com",
  "password": "SecurePassword123!"
}

Success Response

The server returns a 200 OK status code upon successful login. The response body contains a JWT token. Use this token when accessing protected endpoints of the API while logged in.

  • Status Code: 200 OK

  • Body: application/json

Example Success Response

1
2
3

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiNWU2MzU0MTItZmEzYS00MTM1LWIyMmQtZGU5OTAyM2U3YzFmIiwiZXhwIjoxNzU0NzYzOTMwLCJpYXQiOjE3NTQ2Nzc1MzB9.h04h815KK-Jb1YJW3YxzfAkZifTbdUuNs0O5uoVhrPI"
}

Error Responses

Status Code Description Example Body
400 Bad Request The request body is malformed, or required fields (username, password) are missing or invalid. Invalid request payload or `Username and password are required.
401 Unauthorized The username or password is invalid. Invalid username or password
`500 Internal Server Error An unexpected error occured on the server (e.g. database connection issues, failure to generate a JWT token). Failed to generate token

/auth/logout: Log Out

Use this endpoint to log out a user. Upon successful logout, the server invalidates the user’s JWT token.

Endpoint Details

  • Method: POST

  • URL: /auth/logout

Request Body

There is no body content for this request.

Success Response

The server returns a 200 OK status code upon successful logout. The response body is a simple plain-text string.

  • Status Code: 200 OK
  • Body: text/plain

Example Success Response

1

Logged out successfully

Error Responses

Status Code Description Example Body
401 Unauthorized Authorization header is missing, invalid token format or claims, or token expiration time not found. Invalid token format or claims
500 Internal Server Error An unexpected error occured on the server (e.g. database connection issues, failure to revoke the JWT token). Failed to revoke token

Article Endpoints

/articles: Get User’s Articles

Use this end point to retrieve all articles from the server for the logged in user.

Endpoint Details

Method: GET

URL: /articles

Request Body

There is no content for the request body.

Success Response

The server returns a 200 OK status code upon successful retrieval of the personal reading list of articles. The response body contains a list of articles and their details, such as URL, title, summary, and status.

Status Code: 200 OK

Body: application/json

Example Success Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

[
    {
        "id": "65e494d0-5e58-4d13-9a86-85587e1a06ab",
        "user_id": "0e4600f1-0fef-4bed-8ba2-69f9d7fe3ce1",
        "url": "https://www.engadget.com/wearables/watchos-26-preview-its-the-little-things-140035949.html",
        "title": "watchOS 26 preview: It's the little things",
        "summary": "The article previews watchOS 26, noting that while the updates are not revolutionary, they significantly improve the Apple Watch experience. Key enhancements include:\n\n*   **Liquid Glass treatment:** A subtle visual overhaul across the OS, including semi-transparent buttons and a luminous Smart Stack, making the interface prettier and more unified with other Apple devices.\n*   **Revamped Workout app:** Features an AI-powered \"Workout Buddy\" that provides personalized insights, pep talks, and performance updates based on real-time and historical data. It also integrates Apple Music for auto-playing workout-appropriate music (though this feature had some beta issues).\n*   **Wrist Flick gesture:** A new, easy-to-use gesture (available on Series 9, 10, and Ultra 2) to silence calls, dismiss notifications, and return to the watch face.\n*   **Smarter Messages:** Improved on-device language model for more relevant Smart Reply suggestions and the ability to set custom conversation backgrounds.\n*   **Notes app:** The Notes app is now available on the watch, making it convenient for quick access to lists and reminders.\n*   **Other minor updates:** Categorized Face Gallery and adaptive sound that adjusts volume based on ambient noise.\n\nThe author praises these \"little things\" for making the Apple Watch better, despite Siri still lagging behind competitors like Samsung's Gemini.",
        "tags": [
            "Apple Watch",
            " watchOS 26",
            " Apple",
            " Wearables",
            " Smartwatch",
            " Liquid Glass",
            " Workout Buddy",
            " Wrist Flick",
            " Gestures",
            " Smart Replies",
            " Notes",
            " Siri",
            " AI",
            " Watch Faces",
            " Apple Music",
            " Beta",
            " Preview",
            " Review"
        ],
        "status": "unread",
        "created_at": "2025-08-13T15:52:56.0249546-04:00",
        "updated_at": "2025-08-13T15:53:28.8199398-04:00"
    },
    {
        "id": "8da1996f-b07f-4e03-875a-90d65d6a7154",
        "user_id": "0e4600f1-0fef-4bed-8ba2-69f9d7fe3ce1",
        "url": "https://www.npr.org/2025/08/12/nx-s1-5499539/aol-dial-up-ending",
        "title": "Say bye-bye to the beeps and boops of AOL's dial-up internet service : NPR",
        "summary": "AOL is discontinuing its dial-up internet service, effective September 30. Known for its distinctive \"beeps and boops\" and slow speeds, dial-up connected computers to the internet via standard phone lines using a modem, preventing simultaneous phone use.\n\nAOL, which launched its dial-up service in 1989, played a significant role in popularizing internet access in the 1990s, famously distributing free trial CDs. However, it has largely been replaced by broadband internet. As of 2022, only 0.1% of U.S. households still relied on dial-up, meaning the discontinuation will primarily affect a small number of users, often in rural areas, who will now need to find alternative internet access.",
        "tags": [
            "AOL",
            " Dial-up Internet",
            " Internet Service",
            " Technology",
            " Internet History",
            " Broadband",
            " Digital Divide",
            " Modem"
        ],
        "status": "unread",
        "created_at": "2025-08-13T16:03:14.7081106-04:00",
        "updated_at": "2025-08-13T16:03:28.2645073-04:00"
    },
    {
        "id": "51ebf8fe-a109-4602-a68a-0efef44c9de9",
        "user_id": "0e4600f1-0fef-4bed-8ba2-69f9d7fe3ce1",
        "url": "https://www.404media.co/googles-ai-is-destroying-search-the-internet-and-your-brain/",
        "title": "Google’s AI Is Destroying Search, the Internet, and Your Brain",
        "summary": "The article criticizes Google's AI Overview feature, arguing it is detrimental to search, the broader internet, and users' ability to find reliable information. According to a Pew Research Center report cited in the article, Google users who encounter an AI summary are significantly less likely to click on external website links, with only 1% clicking the link provided within the AI summary itself. The author contends that this shift away from the traditional \"10 blue links\" format will severely reduce traffic to blogs, news sites, and small businesses, potentially destroying their livelihoods. Furthermore, the article highlights concerns that Google's AI is easily fooled, prone to errors, and presents misinformation with unearned confidence.",
        "tags": [
            "Google",
            " AI",
            " Search Engines",
            " AI Overview",
            " Internet",
            " Misinformation",
            " Digital Publishing"
        ],
        "status": "unread",
        "created_at": "2025-08-13T16:04:44.6178948-04:00",
        "updated_at": "2025-08-13T16:04:58.7063073-04:00"
    }
]

Error Responses

This endpoint may return the following error codes:

Status Code Description Example Body
401 Unauthorized User ID was not found. Invalid username or password
500 Internal Server Error An unexpected error occurred on the server (e.g., database connection issues, failure to retrieve articles). Failed to fetch articles

/articles: Post User’s Article

Use this end point to save an article to the logged-in user’s personal reading list.

Endpoint Details

  • Method: POST

  • URL: /articles

Request Body

The request body contains the URL for the article to be saved to the user’s reading list.

Field Type Description Required Example
URL string The URL for the article to be saved. Yes http://example.com/article-19

Example Request

1
2
3

{
  "URL": "https://ca.news.yahoo.com/perseids-meteor-shower-will-peak-tomorrow-night-when-and-where-to-watch-170732721.html"
}

Success Response

The server returns a 201 Created status code upon successfuly saving the article’s URL. The response body contains the saved article’s identifier and the logged in user identifier. Initially, the status is set to processing while the server is in the process of retrieving the article’s title and creating a summary and tags for the article. This process may take a minute or two.

Status Code: 201 Created

Body: application/json

Example Success Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
    "id": "7406e5bf-def2-4efa-9e3e-cfefcfea6602",
    "user_id": "0e4600f1-0fef-4bed-8ba2-69f9d7fe3ce1",
    "url": "https://ca.news.yahoo.com/perseids-meteor-shower-will-peak-tomorrow-night-when-and-where-to-watch-170732721.html",
    "title": "",
    "tags": null,
    "status": "processing",
    "created_at": "2025-08-13T14:50:48.9746819-04:00",
    "updated_at": "2025-08-13T14:50:48.9746819-04:00"
}

Error Responses

This endpoint may return the following error codes:

Status Code Description Example Body
400 Bad Request Invalid request payload or missing fields. Invalid request payload or URL is required
401 Unauthorized User ID not found. User ID not found
500 Internal Server Error An unexpected error occurred on the server (e.g., database connection issues, failure to submit article). Failed to sumbit article

/articles/{id}: Get Article By ID

Use this endpoint to retrieve an article by including the ID in the endpoint.

Endpoint details

  • Method: GET

  • URL: /articles/{id}

Request Body

There is no content for the request body.

Success Response

The server returns a 200 OK status code upon successfully retrieving the article specified by the ID in the endpoint. The response body contains the article details.

Example Success Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

{
    "id": "65e494d0-5e58-4d13-9a86-85587e1a06ab",
    "user_id": "0e4600f1-0fef-4bed-8ba2-69f9d7fe3ce1",
    "url": "https://www.engadget.com/wearables/watchos-26-preview-its-the-little-things-140035949.html",
    "title": "watchOS 26 preview: It's the little things",
    "summary": "The article previews watchOS 26, noting that while the updates are not revolutionary, they significantly improve the Apple Watch experience. Key enhancements include:\n\n*   **Liquid Glass treatment:** A subtle visual overhaul across the OS, including semi-transparent buttons and a luminous Smart Stack, making the interface prettier and more unified with other Apple devices.\n*   **Revamped Workout app:** Features an AI-powered \"Workout Buddy\" that provides personalized insights, pep talks, and performance updates based on real-time and historical data. It also integrates Apple Music for auto-playing workout-appropriate music (though this feature had some beta issues).\n*   **Wrist Flick gesture:** A new, easy-to-use gesture (available on Series 9, 10, and Ultra 2) to silence calls, dismiss notifications, and return to the watch face.\n*   **Smarter Messages:** Improved on-device language model for more relevant Smart Reply suggestions and the ability to set custom conversation backgrounds.\n*   **Notes app:** The Notes app is now available on the watch, making it convenient for quick access to lists and reminders.\n*   **Other minor updates:** Categorized Face Gallery and adaptive sound that adjusts volume based on ambient noise.\n\nThe author praises these \"little things\" for making the Apple Watch better, despite Siri still lagging behind competitors like Samsung's Gemini.",
    "tags": [
        "Apple Watch",
        " watchOS 26",
        " Apple",
        " Wearables",
        " Smartwatch",
        " Liquid Glass",
        " Workout Buddy",
        " Wrist Flick",
        " Gestures",
        " Smart Replies",
        " Notes",
        " Siri",
        " AI",
        " Watch Faces",
        " Apple Music",
        " Beta",
        " Preview",
        " Review"
    ],
    "status": "unread",
    "created_at": "2025-08-13T15:52:56.0249546-04:00",
    "updated_at": "2025-08-13T15:53:28.8199398-04:00"
}

Error Responses

This endpoint may return the following error codes:

Status Code Description Example Body
400 Bad Request Article ID must be included in the endpoint. Article ID is required
401 Unauthorized User ID not found. User ID not found
404 Not Found Article was not found for this user. Article not found or not owned by user
500 Internal server error An unexpected error occurred on the server (e.g., database connection issues, failure to retrieve article). Failed to fetch article

/articles/{id}: Delete Article by ID

Use this endpoint to delete an article by including the ID in the endpoint.

Endpoint Details

  • Method: DELETE

  • URL: /articles/{id}

Request Body

There is no content for the request body.

Success Response

The server returns a 204 No Content upon successful deletion of the article from the user’s personal reading list.

Example Success Response

There is no content in the response body.

Error Responses

This endpoint may return the following error codes:

Status Code Description Example Body
400 Bad Request Article ID must be included in the endpoint. Article ID is required
401 Unauthorized User ID not found. User ID not found
404 Not Found Article was not found for this user. Article not found or not owned by user
500 Internal server error An unexpected error occurred on the server (e.g., database connection issues, failure to delete article). Failed to delete article

/articles/{id}/status: Update Article’s Status

Use this endpoint to update an article’s status by including the article ID in the endpoint, and the new status in the request body.

Endpoint Details

  • Method: PUT

  • URL: /articles/{id}/status

Request Body

The request body contains the new status for the specified article in the logged-in user’s personal reading list.

Field Type Description Required Example
status string The new status of the article. Yes read

Example Request

1
2
3

{
  "status": "read"
}

Success Response

The server returns a 200 OK status code upon successful update of the article’s status.

Example Success Response

1

{"message":"Status updated successfully"}

Error Responses

This endpoint may return the following error codes:

Status Code Description Example Body
400 Bad Request Article ID must be included in the endpoint. Article ID is required
401 Unauthorized User ID not found. User ID not found
404 Not Found Article was not found for this user. Article not found or not owned by user
500 Internal server error An unexpected error occurred on the server (e.g., database connection issues, failure to update article status). Failed to update article status

/articles/{id}/tags: Update Article’s Tags

Use this endpoint to update the tags for an article by including the article ID in the endpoint, and the updated list of tags in the request body.

Endpoint Details

  • Method: PUT

  • URL: /articles/{id}/tags

Request Body

The request body should be a JSON object containing the updated list of tags for the article.

Field Type Description Required Example
tags array of strings The updated list of tags for the article Yes ["AOL"," Dial-up Internet"]

Example Request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

{
    "tags": [
        "Apple Watch",
        " watchOS 26",
        " Apple",
        " Wearables",
        " Smartwatch",
        " Liquid Glass",
        " Workout Buddy",
        " Wrist Flick",
        " Gestures",
        " Smart Replies",
        " Notes",
        " Siri",
        " AI",
        " Watch Faces",
        " Apple Music",
        " Preview",
        " Review"
    ]
}

Success Response

The server returns a 200 OK status code upon successful update of the article’s tags. The response body contains a json object with a success message.

Example Success Response

1

{"message":"Tags updated successfully"}

This endpoint may return the following error codes:

Status Code Description Example Body
400 Bad Request Article ID must be included in the endpoint and tags cannot be empty. Article ID is required or Tags cannot be empty
401 Unauthorized User ID not found. User ID not found
404 Not Found Article was not found for this user or not owned by user. Article not found or not owned by user
500 Internal server error An unexpected error occurred on the server (e.g., database connection issues, failure to update article tags). Failed to update article tags

Tags Endpoint

/tags: Get All Tags for a User

Use this endpoint to retrieve all unique tags from all articles for the logged-in user.

Endpoint Details

  • Method: GET

  • URL: /tags

Request Body

There is no content for the request body.

Success Response

The server sends a 200 OK status code upon successfully retrieving all unique tags for the logged-in user.

Example Success Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

[
    " AI",
    " Internet History",
    " Broadband",
    "Apple Watch",
    " Apple Music",
    " Preview",
    " Technology",
    " Misinformation",
    " Watch Faces",
    " Workout Buddy",
    "AOL",
    " Search Engines",
    " Internet",
    " Siri",
    " Dial-up Internet",
    " Smart Replies",
    " Internet Service",
    " Wearables",
    " Review",
    " Digital Divide",
    " Modem",
    " AI Overview",
    " Digital Publishing",
    " Apple",
    " Liquid Glass",
    " Smartwatch",
    " Wrist Flick",
    "Google",
    " watchOS 26",
    " Gestures",
    " Notes"
]

Error Responses

This endpoint may return the following error codes:

Status Code Description Example Body
401 Unauthorized User ID not found. User ID not found
500 Internal server error An unexpected error occurred on the server (e.g., database connection issues, failure to update article tags). Failed to fetch tags for user