Getting Started

A guide to getting started with the API.

Base URL

The base URL for this API is http://localhost:8080/api/v1. If up and running, you will receive a 200 OK status after sending the following GET request using cURL:

curl -i -X GET http://localhost:8080/api/v1

Authentication

Authentication requires initial registration and then logon to the API to use it. The following sections explain how using cURL.

Registration

The endpoint for registration is http://localhost:8080/api/v1/auth/register. Send a POST request with a valid email and password as shown in the following example:

--header 'Content-Type: application/json' \
--data '{
    "username": "testuser@example.com",
    "password": "strongpassword123"
}'

If registration is successful, you will get a 201 Created status response with JSON similar to the following:

1
2
3
4

    "id": "70b8716d-8fcb-4552-bd09-5579318fffd3",
    "username": "testuser@example.com",
    "created_at": "2025-08-04T13:23:22.4373904-04:00"
}

Login

The endpoint for logon is http://localhost:8080/api/v1/auth/login. Log in with your username and password, including the header Content-Type for JSON, as shown in the following example:

--header 'Content-Type: application/json' \
--data '{
    "username": "testuser@example.com",
    "password": "strongpassword123"
}'

If successful, you will receive a 200 OK status response that includes your JWT token in JSON, as shown in the example below:

1
2
3

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiNzBiODcxNmQtOGZjYi00NTUyLWJkMDktNTU3OTMxOGZmZmQzIiwiZXhwIjoxNzU0NDE1OTI3LCJpYXQiOjE3NTQzMjk1Mjd9.dUUlE22W8TuSX5od3MOMC0wx3X2xYf51v04E_aCbm2s"
}

Using Your JWT token

The JWT token is required in the Authorization section of the header for requests to protected endpoints. The example below shows how to save an article to your personal reading list. Use a URL for an article of your choosing. Note that the token is preceded by “Bearer “.

--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiNzBiODcxNmQtOGZjYi00NTUyLWJkMDktNTU3OTMxOGZmZmQzIiwiZXhwIjoxNzU0NDE1OTI3LCJpYXQiOjE3NTQzMjk1Mjd9.dUUlE22W8TuSX5od3MOMC0wx3X2xYf51v04E_aCbm2s' \
--header 'Content-Type: application/json' \
--data '{
    "URL": "https://www.timesnews.net/living/features/kingsport-library-to-offer-intro-to-sewing-for-teens/article_ab8b3fcc-f3a0-4c8f-98b4-4e5337f19054.html"
}'

If your article is successfully saved you will receive a 201 Created status response and JSON similar to the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
    "id": "56ffe2b1-3ade-4384-aef4-594a2619dce0",
    "user_id": "70b8716d-8fcb-4552-bd09-5579318fffd3",
    "url": "https://www.timesnews.net/living/features/kingsport-library-to-offer-intro-to-sewing-for-teens/article_ab8b3fcc-f3a0-4c8f-98b4-4e5337f19054.html",
    "title": "",
    "tags": null,
    "status": "processing",
    "created_at": "2025-08-04T14:02:20.6079382-04:00",
    "updated_at": "2025-08-04T14:02:20.6079382-04:00"
}

More information about the http://localhost:8080/api/v1/articles endpoint and other endpoints is provided in the API Reference section of this document.