API Endpoints
=============

Flask Server Endpoints (api_server.py)
--------------------------------------

The following REST endpoints are exposed by the Flask server running in CT 400.

Health Check
~~~~~~~~~~~~

.. http:get:: /health

   Returns the health status of the Evercycle API Server.

   **Example Request:**

   .. code-block:: bash

      curl -X GET http://api.veraetime.net/health

   **Example Response:**

   .. code-block:: json

      {
        "status": "ok",
        "message": "Evercycle API Server is running"
      }

Authentication
~~~~~~~~~~~~~~

.. http:post:: /api/auth

   Authenticates with the Evercycle backend and stores tokens locally.

   :reqjson string username: Evercycle username
   :reqjson string password: Evercycle password
   :resjson string status: "success" or "error"
   :resjson string message: Human-readable result
   :status 200: Authentication successful
   :status 400: Missing username or password
   :status 401: Authentication failed

   **Example Request:**

   .. code-block:: bash

      curl -X POST http://api.veraetime.net/api/auth \
        -H "Content-Type: application/json" \
        -d '{"username":"user@example.com","password":"secret"}'

   **Example Response (success):**

   .. code-block:: json

      {
        "status": "success",
        "message": "Authentication successful"
      }

List Available APIs
~~~~~~~~~~~~~~~~~~~

.. http:get:: /api/list

   Returns a list of all Evercycle APIs that have JSON config files.

   **Example Response:**

   .. code-block:: json

      {
        "status": "success",
        "apis": [
          {
            "name": "get-all",
            "method": "GET",
            "path": "/v1/asset",
            "description": "Get all Assets"
          }
        ]
      }

Dynamic API Proxy
~~~~~~~~~~~~~~~~~

.. http:any:: /api/<api_name>

   Proxies a request to the Evercycle backend API identified by ``api_name``.
   The HTTP method must match the method declared in the API's JSON config.

   :param api_name: Name of the API config file (without ``.json``)
   :status 200: API call successful
   :status 401: Authentication required or token refresh failed
   :status 404: API config not found or resource not found
   :status 405: HTTP method does not match expected method
   :status 500: Internal server error or API call failed

   **Supported APIs**

   .. list-table::
      :header-rows: 1

      * - api_name
        - Method
        - Evercycle Path
        - Description
      * - auth-signin
        - POST
        - /v1/auth/signin
        - Authenticate user
      * - get-all
        - GET
        - /v1/asset
        - Get all Assets
      * - get-asset-id
        - GET
        - /v1/asset/{id}
        - Get Asset by ID
      * - create
        - POST
        - /v1/asset/create
        - Create a new Asset
      * - create-request
        - POST
        - /v1/asset/request
        - Create an Asset request
      * - edit-asset-id
        - PUT
        - /v1/asset/{id}
        - Edit an Asset
      * - grade
        - PUT
        - /v1/pricebook/{id}/{grade}
        - Update pricebook grade
      * - single-confirm
        - POST
        - /v1/asset/confirm
        - Confirm single asset
      * - by-org
        - GET
        - /v1/asset/org/{org_id}
        - Get assets by organization
      * - programs-list
        - GET
        - /v1/programs
        - List programs
      * - traking-list
        - GET
        - /v1/tracking
        - List tracking items

Evercycle Backend Endpoints
---------------------------

The following endpoints are defined in the markdown specification files inside
``/opt/evercycle-api/evercycle-api/``. They are consumed through the proxy.

/v1/auth/signin
~~~~~~~~~~~~~~~

* **Method:** POST
* **URL:** https://api.evercycle.io/v1/auth/signin
* **Description:** Sign in to Evercycle
* **Headers:** Content-Type: application/json
* **Body:**
  * ``username`` (string)
  * ``password`` (string)
* **Response:** AuthenticationResult object containing AccessToken, ExpiresIn, RefreshToken, IdToken

/v1/asset/create
~~~~~~~~~~~~~~~~

* **Method:** POST
* **URL:** https://api.evercycle.io/v1/asset/create
* **Description:** Create a new Asset for the organization
* **Headers:**
  * ``Authorization`` (IdToken)
  * ``access-token`` (AccessToken)
* **Body Fields:** asset_type_id, year, make, model, serial_number, asset_damage_type_id, damage_description, carrier, cpu, ram, screen, purchase_date, asset_reference, asset_user_first_name, asset_user_last_name, asset_user_address, asset_user_city, asset_user_state, asset_user_postal_code, asset_user_country, request_id, archived, device_master_list_id, service_provider_org_id, asset_user_email, asset_user_phone, end_of_life_date
* **Response:** Created asset object with id, created_at, updated_at

/v1/asset/{id}
~~~~~~~~~~~~~~

* **Method:** GET
* **URL:** https://api.evercycle.io/v1/asset/{id}
* **Description:** Get the Asset information for a given ID
* **Headers:** Authorization, access-token
* **Path Parameters:** id (number)
* **Response:** Asset object

/v1/pricebook/{id}/{grade}
~~~~~~~~~~~~~~~~~~~~~~~~~~

* **Method:** PUT
* **URL:** https://api.evercycle.io/v1/pricebook/{id}/{grade}
* **Description:** Edit an Asset for the given pricebook_catalog_id and grade_name
* **Headers:** Authorization, access-token
* **Path Parameters:** id (number), grade (string)
* **Body Fields:** price (number)
* **Response:** Pricebook object with grade_price array

/v1/asset
~~~~~~~~~

* **Method:** GET
* **URL:** https://api.evercycle.io/v1/asset
* **Description:** Get all Assets
* **Headers:** Authorization, access-token
* **Query Parameters:** page_num, per_page
* **Response:** Array of Asset objects