Quick Start
===========

This page shows the most common operations in a single end-to-end script so you
can get up and running in minutes.

Connect to Agora
----------------

.. code-block:: python

   from gtagora import Agora

   agora = Agora.create('https://agora.mycompany.com', api_key='<YOUR_API_KEY>')

All subsequent calls go through the ``agora`` object, which holds the
authenticated HTTP session.

.. tip::

   Store your API key in an environment variable and read it with
   ``os.environ['AGORA_API_KEY']`` to avoid committing secrets to version
   control.

Browse your data
----------------

.. code-block:: python

   # Navigate the "My Agora" project
   myagora     = agora.get_myagora()
   root_folder = myagora.get_root_folder()

   # List top-level sub-folders
   for folder in root_folder.get_folders():
       print(folder.name)

   # Drill into a specific folder
   data_folder = root_folder.get_folder('MRI Data')
   for exam in data_folder.get_exams():
       print(f'  Exam: {exam.name}')

Create a folder
---------------

.. code-block:: python

   # get_or_create avoids an exception when the folder already exists
   results_folder = root_folder.get_or_create('Results/2024')

Upload data
-----------

.. code-block:: python

   from pathlib import Path

   files = [Path('/local/data/scan.raw'), Path('/local/data/scan.lab')]
   root_folder.upload(files)

Download data
-------------

.. code-block:: python

   from pathlib import Path

   target = Path('/local/downloads')
   exam   = agora.get_exam(42)
   downloaded = exam.download(target)
   for f in downloaded:
       print(f)

Full example
------------

The following script ties the steps above together into a typical workflow:
create a folder, upload two files, wait for the import to complete, then
list the resulting series.

.. code-block:: python

   import os
   from pathlib import Path
   from gtagora import Agora

   agora  = Agora.create(os.environ['AGORA_SERVER'], api_key=os.environ['AGORA_API_KEY'])
   folder = agora.get_myagora().get_root_folder().get_or_create('My Uploads')

   files  = [Path('/data/raw/scan.raw'), Path('/data/raw/scan.lab')]
   folder.upload(files)

   # Inspect what was imported
   for exam in folder.get_exams():
       for series in exam.get_series():
           print(f'{exam.name} / {series.name}')

Next steps
----------

* :doc:`examples/index` – in-depth examples for every resource type
* :doc:`api/index` – full API reference