Quickstart Guide
================

Install API package
-------------------

.. code-block::

   pip install -U http://deployments.molcube.com/api/molcube-0.4.0-py3-none-any.whl

Obtain API key
--------------

To retrieve the API key for a user, there are two methods available:

Case 1: Generate API key programmatically

    Use your MolCube-Builder account credentials (username and password) to generate an API key via generate_api_key() method.
    Use the generated API key for authentication.

Case 2: Generate API key from web application

    Log in to the MolCube-Builder web application and navigate to the Profile page.
    Generate an API key and copy the key value.
    Use the copied API key for authentication.

Additional Notes

    The API key does not have an expiration time.
    If a new API key is generated using either method, the previous API key will be invalidated and can no longer be used.
    For security reasons, remember to store your API key securely and never commit it to version control.

Authenticate API Client
-----------------------

For On-Premise (>= v2025.2.5) Users::

   molcube = mc.API('localhost', 8000, is_onprem=True)

For other users::

   # Initialize MolCube API client
   molcube = mc.API('api.molcube.com', 443)

   # Case 1: Generate API key with username and password, then authenticate
   # username = "your_username"
   # password = "your_password"
   # api_key = molcube.generate_api_key(username=username, password=password)
   # molcube.authenticate(api_token=api_key)

   # Case 2: Authenticate with an existing API key
   api_access_key = "49093487b5db40b0ad6009cc014675b7"
   molcube.authenticate(api_token=api_access_key)

Minimal project example
-----------------------

This example loads 2hac from disk and uses default options only::

   import molcube as mc
   from pprint import pprint

   molcube = mc.API('api.molcube.com', 443)
   molcube.authenticate(api_token=api_access_key)

   # simplest possible case: use defaults for everything
   pdbreader = molcube.create_pdb_reader_project()
   pdbreader.create_project(title='test-defaults', ff='charmmff', customPdb='files/2hac.cif')
   pdbreader.set_defaults()

   # if modifying chain selection, do so here
   assert pdbreader.confirm_chains()

   # if modifying manipulation options, do so here
   assert pdbreader.model_pdb()

For more detailed examples, see :doc:`user_guide/index`.