### Install Pre-commit Hooks

Source: https://github.com/saagie/api-saagie/blob/master/CONTRIBUTING.md

Run this command to automatically apply linters and code quality checks before each commit.

```bash
poetry run pre-commit install
```

--------------------------------

### Install saagieapi Python Package

Source: https://github.com/saagie/api-saagie/blob/master/README.md

Install the saagieapi package using pip. Specify the desired version for compatibility.

```bash
pip install saagieapi==<version>
```

--------------------------------

### Upgrade an Application

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

This example demonstrates how to upgrade an application by specifying its ID, exposed ports, and storage paths. Ensure the provided IDs and configurations are correct for your application.

```python
>>> saagie_client.apps.upgrade(
...     app_id="97ec670f-8b11-479f-9cd2-c8904ef45b7f",
...     exposed_ports=[
...         {
...             "basePathVariableName": "SAAGIE_BASE_PATH",
...             "isRewriteUrl": True,
...             "scope": "PROJECT",
...             "number": 80,
...             "name": "Test Port"
...         }
...     ],
...     storage_paths=[
...         {
...             "path": "/home",
...             "volumeId": "00f5d5d4-1975-478b-81f3-2003b7cff4c2"
...         }
...     ]
... )
{
    'addAppVersion': {
        'number': 2,
        'releaseNote': '',
        'dockerInfo': None,
        'ports': [
            {
                'number': 80,
                'name': 'Test Port',
                'basePathVariableName': 'SAAGIE_BASE_PATH',
                'isRewriteUrl': True,
                'scope': 'PROJECT'
            }
        ],
        'volumesWithPath': [
            {
                'path': '/home',
                'volume': {
                    'id': '62f5d5d4-9546-478b-81f3-1970b7cff4c2',
                    'name': 'storage 64MB',
                    'size': '64 MB',
                    'creator': 'titi.tata'
                }
            }
        ]
    }
}
```

--------------------------------

### Create a Simple Pipeline with Two Jobs

Source: https://github.com/saagie/api-saagie/blob/master/docs/Pipelines/index.md

Illustrates creating a basic pipeline with two sequential jobs. This is a foundational example for building more complex pipelines.

```python
job_node1 = JobNode(job_id_1)
job_node2 = JobNode(job_id_2)
job_node1.add_next_node(job_node2) # Indicates that the job_node_1 is followed by job_node_2
graph_pipeline = GraphPipeline()
graph_pipeline.add_root_node(job_node1) # Indicates the pipeline will start with job_node1
```

--------------------------------

### Get Platform Information

Source: https://github.com/saagie/api-saagie/blob/master/docs/Platform/index.md

Fetches overall platform statistics, including the number of projects, jobs, applications, and pipelines. Use this to get a high-level overview of platform usage.

```python
>>> saagie_api.get_platform_info()
{
    "platform": {
        "id": 1,
        "counts": {
            "projects": 21,
            "jobs": 111,
            "apps": 59,
            "pipelines": 17
        }
    }
}
```

--------------------------------

### Get Saagie Project App Technologies

Source: https://github.com/saagie/api-saagie/blob/master/docs/Projects/index.md

Retrieve a list of available application technologies for a given Saagie project. The result can be pretty-printed if desired.

```python
>>> saagieapi.projects.get_apps_technologies(project_id="8321e13c-892a-4481-8552-5be4d6cc5df4")
{
    'appTechnologies': [
        {
            'id': '11d63963-0a74-4821-b17b-8fcec4882863'
        },
        {
            'id': '56ad4996-7285-49a6-aece-b9525c57c619'
        },
        {
            'id': 'd0b55623-9dc0-4e03-89c7-6a2494387a4f'
        }
    ]
}
```

--------------------------------

### Get Saagie App History Statuses

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

Retrieve the historical status updates for a specific app version, starting from a given timestamp. Requires app history ID, version number, and start time.

```python
>>> saagieapi.apps.get_history_statuses(
...     history_id="55943477-c41b-4dfe-a8ca-c110909d9204",
...     version_number=2,
...     start_time="2023-07-31T14:26:27.073Z"
... )
{
    'appHistoryStatuses': [
        {'status': 'STARTING', 'recordAt': '2023-08-01T08:38:34.859Z'},
        {'status': 'STARTED', 'recordAt': '2023-08-01T08:38:38.845Z'},
        {'status': 'FAILED', 'recordAt': '2023-08-01T08:38:39.875Z'},
        {'status': 'RECOVERING', 'recordAt': '2023-08-01T08:38:39.875Z'},
        {'status': 'STOPPING', 'recordAt': '2023-08-01T08:38:41.094Z'},
        {'status': 'STOPPED', 'recordAt': '2023-08-01T08:38:41.241Z'}
    ]
}
```

--------------------------------

### Create App from Scratch

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

This snippet demonstrates creating an application from scratch, allowing for custom configurations like Docker image, exposed ports, and storage paths. Ensure the image is specified or provide technology details.

```python
>>> saagieapi.apps.create_from_scratch(
...     project_id="project_id",
...     app_name="App Example Scratch",
...     image="saagie/ttyd-saagie:1.0",
...     exposed_ports=[
...         {
...             "basePathVariableName": "SAAGIE_BASE_PATH",
...             "isRewriteUrl": True,
...             "scope": "PROJECT",
...             "number": 7681,
...             "name": "ttyd"
...         }
...     ]
... )
{
    'createApp': {
        'id': '1221f83e-52de-4beb-89a0-1505de4e875f'
    }
}
```

--------------------------------

### Get App History Statuses

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

Retrieves the history of statuses for a specific application version, starting from a given time.

```APIDOC
## get_history_statuses(history_id, version_number, start_time)

### Description
Get statuses history of the app

### Parameters
* **history_id** (*str*) – UUID of your app history
* **version_number** (*str*) – Number of the version to get the statuses history
* **start_time** (*str*) – Date since to get the statuses history (format : “%Y-%m-%dT%H:%M:%S.%fZ”)

### Returns
Dict of app’s statuses history

### Return type
dict

### Examples
```pycon
>>> saagieapi.apps.get_history_statuses(
...     history_id="55943477-c41b-4dfe-a8ca-c110909d9204",
...     version_number=2,
...     start_time="2023-07-31T14:26:27.073Z"
... )
{
    'appHistoryStatuses': [
        {'status': 'STARTING', 'recordAt': '2023-08-01T08:38:34.859Z'},
        {'status': 'STARTED', 'recordAt': '2023-08-01T08:38:38.845Z'},
        {'status': 'FAILED', 'recordAt': '2023-08-01T08:38:39.875Z'},
        {'status': 'RECOVERING', 'recordAt': '2023-08-01T08:38:39.875Z'},
        {'status': 'STOPPING', 'recordAt': '2023-08-01T08:38:41.094Z'},
        {'status': 'STOPPED', 'recordAt': '2023-08-01T08:38:41.241Z'}
    ]
}
```
```

--------------------------------

### Create App from Catalog

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

This method allows you to create a new application by selecting a pre-defined application from the catalog. You need to provide the project ID, the desired context (e.g., version), and the technology name of the application you want to install.

```APIDOC
## create_from_catalog

### Description
Creates an application from a catalog entry within a specified project.

### Parameters
#### Path Parameters
- **project_id** (str) - Required - ID of the project.
- **context** (str) - Required - The version or context of the application to install.
- **technology_name** (str) - Required - The name of the technology or application to install from the catalog.

### Request Example
```python
saagieapi.apps.create_from_catalog(
    project_id="your_project_id",
    context="7.15.1",
    technology_name="kibana"
)
```

### Response
#### Success Response (200)
- **installApp** (dict) - Contains details of the installed application, including its ID and name.
```

--------------------------------

### Get Application Statistics

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

Retrieves performance statistics for an application's history. Requires the history ID, version number, and a start time for the statistics query.

```python
saagieapi.apps.get_stats(
    history_id="55943477-c41b-4dfe-a8ca-c110909d9204",
    version_number=2,
    start_time="2024-04-10T14:26:27.073Z"
)
```

--------------------------------

### Connect to Saagie Platform with Easy Connect Constructor

Source: https://github.com/saagie/api-saagie/blob/master/docs/index.md

This constructor simplifies connection by parsing a complete platform URL to extract necessary details like platform URL, ID, and realm.

```python
saagie = SaagieApi.easy_connect(url_saagie_platform="<url>",
                                user="<saagie-user-name>",
                                password="<saagie-user-password>")
```

--------------------------------

### Create App from Catalog

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

Use this snippet to create a new application by selecting a pre-defined technology from the catalog. Specify the project ID, context version, and the technology name.

```python
>>> saagieapi.apps.create_from_catalog(
...     project_id="your_project_id",
...     context="7.15.1",
...     technology_name="kibana"
... )
{
    'installApp': {
        'id': 'a6de6956-4038-493e-bbd3-f7b3616df39e',
        'name': 'Kibana'
    }
}
```

--------------------------------

### Get Storage

Source: https://github.com/saagie/api-saagie/blob/master/docs/Storages/index.md

Retrieves storage information using a storage ID. This is the recommended method for getting storage details.

```APIDOC
## get(storage_id: str)

### Description
Get storage information by storage ID.

### Parameters
#### Path Parameters
* **storage_id** (str) - UUID of your storage

### Request Example
```python
saagieapi.storages.get(
    storage_id="f5fce22d-2152-4a01-8c6a-4c2eb4808b6d"
)
```

### Response
#### Success Response (200)
- **volume** (dict) - Contains detailed information about the storage volume.
  - **id** (str) - Unique identifier of the storage volume.
  - **name** (str) - Name of the storage volume.
  - **size** (str) - Size of the storage volume.
  - **description** (str) - Description of the storage volume.
  - **creationDate** (str) - Date and time when the storage was created.
  - **creator** (str) - User who created the storage.
  - **linkedApp** (dict) - Information about the application linked to this storage.
  - **originalVolumeId** (str) - The ID of the original volume if this is a duplicate.
  - **duplicationStatus** (str) - Status of the duplication process.
  - **isLocked** (bool) - Indicates if the storage is locked.

#### Response Example
```json
{
    "volume":
    {
        "id":"89bf5f86-3fc3-4bf6-879b-7ca8eafe6c4f",
        "name":"storage Jupyter Notebook (0)",
        "size":"64 MB",
        "description":"Autogenerated storage from app installation for \"/notebooks-dir\" path in \"Jupyter Notebook\" app.",
        "creationDate":"2022-08-26T13:12:05.363Z",
        "creator":"user.name",
        "linkedApp":{
            "id":"6871e9a2-2c06-45fe-bf8d-6356090f1d1d",
            "name":"Jupyter Notebook",
            "versions":[
                {
                    "number":1,
                    "volumesWithPath":[
                        {
                            "path":"/notebooks-dir",
                            "volume":{
                                "id":"89bf5f86-3fc3-4bf6-879b-7ca8eafe6c4f"
                            }
                        }
                    ]
                }
            ],
            "currentVersion":{
                "number":1,
                "volumesWithPath":[]
            }
        },
        "originalVolumeId":"None",
        "duplicationStatus":"None",
        "isLocked":false
    }
}
```
```

--------------------------------

### Connect to Saagie Platform with Default Constructor

Source: https://github.com/saagie/api-saagie/blob/master/docs/index.md

Use this constructor when you have all connection details readily available, including platform ID and realm.

```python
saagie = SaagieApi(url_saagie="<url>",
                   id_platform="1",
                   user="<saagie-user-name>",
                   password="<saagie-user-password>",
                   realm="saagie")
```

--------------------------------

### Create App from Scratch

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

This method enables the creation of a new application from scratch, allowing for detailed configuration including image, ports, storage, resources, and technology specifics. It's suitable for custom application deployments.

```APIDOC
## create_from_scratch

### Description
Create an app in a specific project from scratch with detailed configuration.

### Parameters
#### Path Parameters
- **project_id** (str) - Required - ID of the project.
- **app_name** (str) - Required - Name of the app.

#### Query Parameters
- **description** (str) - Optional - Description of the app.
- **image** (str) - Optional - Tag of the Docker Image. Incompatible with parameters technology_id & technology_context.
- **docker_credentials_id** (str) - Optional - Credentials’s ID for the image if the image is not public. Incompatible with parameters technology_id & technology_context.
- **exposed_ports** (list of dict) - Optional - List of dictionaries of exposed ports. Each dict should contain ‘port’ as key.
- **storage_paths** (list of dict) - Optional - List of dictionaries indicating the volume path to the persistent storage and the id of the volume to be associated with the app, or the information needed to create the volume.
- **release_note** (str) - Optional - Release note for the app version.
- **emails** (list of str) - Optional - Emails to receive alerts for the app.
- **logins** (list of str) - Optional - Logins to receive alerts for the app.
- **status_list** (list of str) - Optional - Receive an email when the app status changes to a specific status.
- **resources** (dict) - Optional - Resources CPU, RAM & GPU limited and guaranteed for the app.
- **technology_id** (str) - Optional - Technology id of the app. Incompatible with parameters image & docker_credentials_id.
- **technology_context** (str) - Optional - Context version of the app. Incompatible with parameters image & docker_credentials_id.

### Request Example
```python
saagieapi.apps.create_from_scratch(
    project_id="project_id",
    app_name="App Example Scratch",
    image="saagie/ttyd-saagie:1.0",
    exposed_ports=[
        {
            "basePathVariableName": "SAAGIE_BASE_PATH",
            "isRewriteUrl": True,
            "scope": "PROJECT",
            "number": 7681,
            "name": "ttyd"
        }
    ]
)
```

### Response
#### Success Response (200)
- **createApp** (dict) - Contains the ID of the created application.
```

--------------------------------

### get

Source: https://github.com/saagie/api-saagie/blob/master/docs/Environment Variables/index.md

Retrieves information about a specific environment variable.

```APIDOC
## get(scope: str, name: str, project_id: str = None, pipeline_id: str = None, app_id: str = None, scope_only: bool = False, pprint_result: bool | None = None)

### Description
Gets environment variable information. Note: You can only get environment variable information if you have at least the viewer role on the project.

### Parameters
#### Path Parameters
- **scope** (str) - Required - Scope of the environment variable to get. Must be one of GLOBAL, PROJECT, PIPELINE or APP.
- **name** (str) - Required - Name of the environment variable to get.
- **project_id** (str) - Optional - UUID of your project.
- **pipeline_id** (str) - Optional - UUID of your pipeline.
- **app_id** (str) - Optional - UUID of your app.
- **scope_only** (bool) - Optional - Whether to return only the environment variables of the given scope.
- **pprint_result** (bool) - Optional - Whether to pretty print the result of the query, defaults to saagie_api.pprint_global.

### Request Example
```python
saagieapi.env_vars.get(scope="GLOBAL", name="TEST_GLOBAL_ENV_VARS")
```

### Response
#### Success Response (200)
- **get** (dict) - Dictionary containing environment variable details, or None if not found.
```

--------------------------------

### Get Application Info

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

Retrieves detailed information about a specific application using its ID.

```APIDOC
## Get Application Info

### Description
Retrieves detailed information about a specific application using its ID.

### Method
GET (assumed, based on SDK method name 'get_info')

### Endpoint
`/apps/{app_id}` (inferred)

### Parameters
#### Path Parameters
- **app_id** (string) - Required - The unique identifier of the application.

### Request Example
```python
saagieapi.apps.get_info(app_id="your_app_id")
```

### Response
#### Success Response (200)
- **app** (object) - Contains detailed information about the application.
  - **id** (string) - The unique identifier of the application.
  - **name** (string) - The name of the application.
  - **creationDate** (string) - The date and time when the application was created.
  - **technology** (object) - Information about the technology used by the application.
    - **id** (string) - The unique identifier of the technology.
  - **project** (object) - Information about the project the application belongs to.
    - **id** (string) - The unique identifier of the project.
    - **name** (string) - The name of the project.
  - **description** (string) - A description of the application.
  - **currentVersion** (object) - Information about the current version of the application.
    - **number** (integer) - The version number.
    - **creator** (string) - The user who created the version.
    - **creationDate** (string) - The date and time when the version was created.
    - **releaseNote** (string) - Release notes for the version.
    - **dockerInfo** (object or null) - Docker image information.
    - **runtimeContextId** (string) - The ID of the runtime context.
    - **ports** (array) - List of ports exposed by the application.
      - **name** (string) - The name of the port.
      - **number** (integer) - The port number.
      - **isRewriteUrl** (boolean) - Indicates if the URL should be rewritten.
      - **basePathVariableName** (string) - The base path variable name.
      - **scope** (string) - The scope of the port.
      - **internalUrl** (string) - The internal URL for the port.
    - **volumesWithPath** (array) - List of volumes mounted with paths.
      - **path** (string) - The mount path for the volume.
      - **volume** (object) - Information about the volume.
        - **id** (string) - The unique identifier of the volume.
        - **name** (string) - The name of the volume.
        - **creator** (string) - The user who created the volume.
        - **description** (string) - A description of the volume.
        - **size** (string) - The size of the volume.
        - **projectId** (string) - The ID of the project the volume belongs to.
        - **creationDate** (string) - The date and time when the volume was created.
        - **linkedApp** (object) - Information about the application linked to the volume.
          - **id** (string) - The unique identifier of the linked application.
          - **name** (string) - The name of the linked application.
    - **isMajor** (boolean) - Indicates if this is a major version.
  - **history** (object) - Information about the application's execution history.
    - **id** (string) - The unique identifier of the history.
    - **currentStatus** (string) - The current status of the application.
    - **currentExecutionId** (string) - The ID of the current execution.
    - **currentDockerInfo** (object) - Information about the current Docker container.
      - **image** (string) - The Docker image used.
      - **dockerCredentialsId** (null) - Docker credentials ID (if applicable).
    - **startTime** (string) - The start time of the current execution.
    - **events** (array) - A list of events in the application's history.
      - **event** (object) - Details of an event.
        - **recordAt** (string) - The timestamp of the event record.
        - **executionId** (string) - The ID of the execution associated with the event.
        - **versionNumber** (integer) - The version number at the time of the event.
        - **author** (string) - The author of the event.
        - **status** (string) - The status of the application at the time of the event.

### Response Example
```json
{
    "app": {
        "id": "b6e846d7-d871-46db-b858-7d39d6b60123",
        "name": "Jupyter lab",
        "creationDate": "2022-05-09T14:12:31.819Z",
        "technology": {
            "id": "7d3f247c-b5a9-4a34-a0a2-f6b209bc2b63"
        },
        "project": {
            "id": "96a74193-303d-43cf-adb2-a7300d5bb9df",
            "name": "Saagie testing tool "
        },
        "description": "",
        "currentVersion": {
            "number": 1,
            "creator": "toto.hi",
            "creationDate": "2022-05-09T14:12:31.819Z",
            "releaseNote": "First version of Jupyter Notebook with Spark 3.1 into Saagie.",
            "dockerInfo": null,
            "runtimeContextId": "jupyter-spark-3.1",
            "ports": [
                {
                    "name": "Notebook",
                    "number": 8888,
                    "isRewriteUrl": false,
                    "basePathVariableName": "SAAGIE_BASE_PATH",
                    "scope": "PROJECT",
                    "internalUrl": "http://app-b6e846d7-d871-46db-b858-7d39d6b60146:8888"
                },
                {
                    "name": "SparkUI",
                    "number": 8080,
                    "isRewriteUrl": false,
                    "basePathVariableName": "SPARK_UI_PATH",
                    "scope": "PROJECT",
                    "internalUrl": "http://app-b6e846d7-d871-46db-b858-7d39d6b60146:8080"
                }
            ],
            "volumesWithPath": [
                {
                    "path": "/notebooks-dir",
                    "volume": {
                        "id": "c163216a-b024-4cb1-8aae-0664bf2f58b4",
                        "name": "storage Jupyter lab",
                        "creator": "toto.hi",
                        "description": "Automatically created by migration from app c163216a-b024-4cb1-8aae-0664bf2f58b4",
                        "size": "128 MB",
                        "projectId": "96a74193-303d-43cf-adb2-a7300d5bb9df",
                        "creationDate": "2022-05-09T14:12:31.819Z",
                        "linkedApp": {
                            "id": "b6e846d7-d871-46db-b858-7d39d6b60146",
                            "name": "Jupyter lab"
                        }
                    }
                }
            ],
            "isMajor": false
        },
        "history": {
            "id": "4f60dd23-4ec2-4996-b4da-d95376d72387",
            "currentStatus": "STARTED",
            "currentExecutionId": "f2d81d93-e1ae-4b09-a77e-4e50c13971ce",
            "currentDockerInfo": {
                "image": "saagie/jupyter-python-nbk:pyspark-3.1.1-1.111.0",
                "dockerCredentialsId": null
            },
            "startTime": "2022-09-21T09:47:27.342Z",
            "events": [
                {
                    "event": {
                        "recordAt": "2022-06-21T12:57:22.734Z",
                        "executionId": "7eb4649c-2bcf-4062-a7d2-528a9d950e6d",
                        "versionNumber": 1,
                        "author": "user.test"
                    }
                },
                {
                    "event": {
                        "recordAt": "2022-06-21T12:57:22.9Z",
                        "executionId": "7eb4649c-2bcf-4062-a7d2-528a9d950e6d",
                        "status": "STARTING"
                    }
                },
                {
                    "event": {
                        "recordAt": "2022-06-21T12:57:35.443Z",
                        "executionId": "7eb4649c-2bcf-4062-a7d2-528a9d950e6d",
                        "status": "STARTED"
                    }
                },
                {
                    "event": {
                        "recordAt": "2022-06-24T14:28:01.647Z",
                        "executionId": "7eb4649c-2bcf-4062-a7d2-528a9d950e6d",
                        "author": "user.test"
                    }
                },
                {
                    "event": {
                        "recordAt": "2022-06-24T14:28:01.726Z",
                        "executionId": "7eb4649c-2bcf-4062-a7d2-528a9d950e6d",
                        "status": "STOPPING"
                    }
                },
                {
                    "event": {
                        "recordAt": "2022-06-24T14:28:01.81Z",
                        "executionId": "7eb4649c-2bcf-4062-a7d2-528a9d950e6d",
                        "status": "STOPPED"
                    }
                },
                {
                    "event": {
                        "recordAt": "2022-06-29T07:41:41.713Z",
                        "executionId": "9e525435-684f-470e-9818-fb865776da09",
                        "versionNumber": 1,
                        "author": "user.test"
                    }
                },
                {
                    "event": {
                        "recordAt": "2022-06-29T07:41:41.713Z",
                        "executionId": "9e525435-684f-470e-9818-fb865776da09",
                        "status": "STARTING"
                    }
                }
            ]
        }
    }
}
```

```

--------------------------------

### Get Repository ID

Source: https://github.com/saagie/api-saagie/blob/master/docs/Repositories/index.md

Retrieves the unique identifier (UUID) of a repository given its name.

```APIDOC
## get_id

### Description
Get the repository id with the repository name

### Method
`get_id(repository_name: str)`

### Parameters
#### Path Parameters
* **repository_name** (str) - Required - Name of your project

### Returns
Repository UUID (str)

### Raises
* **NameError** – If repository does not exist or the user don’t have permission to see it

### Request Example
```pycon
saagieapi.repositories.get_id(repository_name="Saagie")
```
```

--------------------------------

### Get Group Permissions

Source: https://github.com/saagie/api-saagie/blob/master/docs/Groups/index.md

Retrieves the permissions for a specified group. Requires administrator privileges.

```APIDOC
## get_permission group_name [verify_ssl]

### Description
Get group’s permissions. Requires administrator privileges.

### Method
`get_permission`

### Parameters
* **group_name** (*str*) - Required - Name of the group
* **verify_ssl** (*bool* | None) - Optional - Enable or disable verification of SSL certification. Defaults to `saagie_api.verify_ssl`.

### Returns
* **Dict** - Dict of group’s permissions.

### Example
```python
saagieapi.groups.get_permission(group_name="my_group")
```
```

--------------------------------

### run

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

Executes a given application.

```APIDOC
## run(app_id: str) -> Dict

### Description
Run a given app

### Parameters
#### Path Parameters
- **app_id** (str) - Required - UUID of your app (see README on how to find it)

### Returns
Dict of the given app information

### Return type
dict

### Examples
```pycon
>>> saagieapi.apps.run(app_id="a6de6956-4038-493e-bbd3-f7b3616df39e")
{
    'runApp': {
        'id': 'a6de6956-4038-493e-bbd3-f7b3616df39e',
        'versions': [
            {
                'number': 1
            }
        ],
        'history': {
            'id': 'ba494615-88b7-4c54-ad57-34a90461c407',
            'currentDockerInfo': {
                'image': 'saagie/kibana:7.15.1-1.108.0',
                'dockerCredentialsId': None
            },
            'runningVersionNumber': 1,
            'currentStatus': 'STOPPED'
        }
    }
}
```
```

--------------------------------

### Get Job Instance

Source: https://github.com/saagie/api-saagie/blob/master/docs/Jobs/index.md

Retrieves details of a specific job instance using its unique ID.

```APIDOC
## Get Job Instance

### Description
Retrieves details of a specific job instance using its unique ID.

### Method
GET (assumed based on SDK method name `get_instance`)

### Endpoint
`/jobs/{jobInstanceId}/instance` (inferred path)

### Parameters
#### Path Parameters
- **jobInstanceId** (string) - Required - The unique identifier of the job instance.

### Response
#### Success Response (200)
- **jobInstance** (object) - Contains detailed information about the job instance, including its ID, status, version, and execution variables.
```

--------------------------------

### Create a New Repository

Source: https://github.com/saagie/api-saagie/blob/master/docs/Repositories/index.md

Use this method to create a new repository on the Saagie platform. You can provide a local zip file or a URL for the repository content. Ensure the repository name does not already exist.

```python
>>> saagie.repositories.create(
...     name="hello world repo",
...     file="./test_input/technologies.zip"
... )
{
    'addRepository': {
        'count': 1,
        'objects': [
            {
                'id': 'd04e578f-546a-41bf-bb8c-790e99a4f6c8',
                'name': 'hello world repo'
            }
        ]
    }
}
```

--------------------------------

### Extract Platform ID and Realm from URL

Source: https://github.com/saagie/api-saagie/blob/master/docs/index.md

Demonstrates how to parse a Saagie project URL to identify the platform ID and realm.

```text
https://mysaagie-workspace.me.saagie.com/projects/platform/1/
would give :
    - platform_id = 1
    - realm = mysaagie
```

--------------------------------

### Get Available Apps Technologies

Source: https://github.com/saagie/api-saagie/blob/master/docs/Projects/index.md

Lists the available application technology IDs for a given project.

```APIDOC
## Get Available Apps Technologies

### Description
Lists the available application technology IDs for a given project.

### Method
```python
saagieapi.projects.get_apps_technologies(project_id: str, pprint_result: bool | None = None) -> dict
```

### Parameters
#### Path Parameters
- **project_id** (str) - Required - The UUID of your project.
- **pprint_result** (bool, optional) - Whether to pretty print the result of the query. Defaults to the global `saagie_api.pprint_global` setting.

### Request Example
```python
{
    "example": "saagieapi.projects.get_apps_technologies(project_id=\"8321e13c-892a-4481-8552-5be4d6cc5df4\")"
}
```

### Response
#### Success Response (200)
- **appTechnologies** (list[dict]) - A list of dictionaries, where each dictionary contains the 'id' of an available app technology.

#### Response Example
```json
{
    "appTechnologies": [
        {
            "id": "11d63963-0a74-4821-b17b-8fcec4882863"
        },
        {
            "id": "56ad4996-7285-49a6-aece-b9525c57c619"
        },
        {
            "id": "d0b55623-9dc0-4e03-89c7-6a2494387a4f"
        }
    ]
}
```
```

--------------------------------

### Get User Info

Source: https://github.com/saagie/api-saagie/blob/master/docs/Users/index.md

Retrieves detailed information for a specific user. Requires administrator privileges.

```APIDOC
## get_info

### Description
Get info of a specific user

### Method
`get_info(user_name: str, verify_ssl: bool | None = None) -> Dict`

### Parameters
* **user_name** (*str*) – User’s name
* **verify_ssl** (*bool* *,* *optional*) – Enable or disable verification of SSL certification. By default, refers to saagie_api.verify_ssl

### Returns
Dict of user’s information on the platform, the dict have the following structure: {‘login’: ‘str’, ‘roles’: [‘str’], ‘platforms’: [], ‘groups’: [‘str’], ‘protected’: bool}

### Return type
Dict

### Example
```pycon
saagieapi.users.get_info(user_name="test_user")
```
```

--------------------------------

### List Apps for a Project (Minimal)

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

Lists only the names and IDs of apps within a specified project. Requires at least viewer role on the project.

```python
saagieapi.apps.list_for_project_minimal(project_id="your_project_id")
```

--------------------------------

### Get User Information

Source: https://github.com/saagie/api-saagie/blob/master/docs/Users/index.md

Retrieves detailed information for a specific user. Access is restricted to administrators.

```python
>>> saagieapi.users.get_info(user_name="test_user")
{
    "login": "test_user",
    "roles": [
        "ROLE_READER"
    ],
    "platforms": [],
    "groups": [
        "test_group"
    ],
    "protected": False
}
```

--------------------------------

### Run an App

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

Initiates the execution of a specified application. Requires the app's UUID.

```python
saagieapi.apps.run(app_id="a6de6956-4038-493e-bbd3-f7b3616df39e")
```

--------------------------------

### List Apps for a Project

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

Lists all applications within a given project. Can optionally return minimal information (name and ID only). Requires at least viewer role on the project.

```python
saagieapi.apps.list_for_project(project_id="your_project_id")
```

--------------------------------

### Get Job ID

Source: https://github.com/saagie/api-saagie/blob/master/docs/Jobs/index.md

Retrieves the unique identifier (UUID) of a job given its name and the project it belongs to.

```APIDOC
## Get Job ID

### Description
Retrieves the unique identifier (UUID) of a job given its name and the project it belongs to.

### Method
GET (Assumed based on get operation)

### Endpoint
/jobs/id

### Parameters
#### Query Parameters
- **job_name** (string) - Required - The name of the job.
- **project_name** (string) - Required - The name of the project the job belongs to.

### Response
#### Success Response (200)
- **job_id** (string) - The UUID of the job.

#### Response Example
```json
{
  "job_id": "f5fce22d-2152-4a01-8c6a-4c2eb4808b6d"
}
```
```

--------------------------------

### List All Repositories

Source: https://github.com/saagie/api-saagie/blob/master/docs/Repositories/index.md

Retrieves information for all repositories. Access is restricted to users with permissions for the technology catalog. Options to fetch minimal data or only the last synchronization are available.

```python
list(minimal: bool | None = False, last_synchronization: bool = True, pprint_result: bool | None = None) -> Dict
```

--------------------------------

### Get Group Users

Source: https://github.com/saagie/api-saagie/blob/master/docs/Groups/index.md

Retrieves a list of users belonging to a specific group. Requires admin role.

```python
>>> saagieapi.groups.get_users(group_name="test_group")
{
    "name": "test_group",
    "users": ["test_user"],
    "protected": False
}
```

--------------------------------

### create

Source: https://github.com/saagie/api-saagie/blob/master/docs/Environment Variables/index.md

Creates a single environment variable within a specified scope (GLOBAL, PROJECT, PIPELINE, or APP). Allows setting a value, description, and indicating if it's a password.

```APIDOC
## create

### Description
Creates a single environment variable within a specified scope (GLOBAL, PROJECT, PIPELINE, or APP). Allows setting a value, description, and indicating if it's a password.

### Method
POST (Assumed based on creation action)

### Endpoint
`/environment-variables` (Assumed structure)

### Parameters
#### Query Parameters
- **scope** (str) - Required - Scope of the environment variable to create. Must be one of GLOBAL, PROJECT, PIPELINE or APP.
- **name** (str) - Required - Name of the environment variable to create.
- **value** (str) - Optional - Value of the environment variable to create. Defaults to 'DEFAULT_VALUE'.
- **description** (str) - Optional - Description of the environment variable to create.
- **is_password** (bool) - Optional - Weather the environment variable to create is a password or not. Defaults to False.
- **project_id** (str) - Optional - UUID of your project.
- **pipeline_id** (str) - Optional - UUID of your pipeline.
- **app_id** (str) - Optional - UUID of your app.

### Request Example
```json
{
  "scope": "PROJECT",
  "name": "TEST_PASSWORD",
  "value": "test",
  "description": "This is a password",
  "is_password": true,
  "project_id": "50033e21-83c2-4431-a723-d54c2693b964"
}
```

### Response
#### Success Response (200)
- **saveEnvironmentVariable** (dict) - Contains the ID of the saved environment variable.

#### Response Example
```json
{
    "saveEnvironmentVariable": {
        "id": "8aaee333-a9f4-40f5-807a-44f8efa65a2f"
    }
}
```
```

--------------------------------

### Get Group Permissions

Source: https://github.com/saagie/api-saagie/blob/master/docs/Groups/index.md

Retrieves the permissions associated with a specific group. Requires appropriate roles to access.

```python
>>> saagieapi.groups.get_permission(group_name="test_group")
{
    "name": "test_group",
    "role": "ROLE_READER",
    "authorizations": [
        {
            "platformId": 1,
            "platformName": "Dev",
            "permissions": [
                {
                    "artifact": {
                        "type": "PROJECTS_ENVVAR_EDITOR"
                    },
                    "role": "ROLE_PROJECT_ENVVAR_EDITOR"
                },
                {
                    "artifact": {
                        "id": "87ad5abb-5ee9-4e7d-8c82-5b40378ad931",
                        "type": "PROJECT"
                    },
                    "role": "ROLE_PROJECT_MANAGER"
                }
            ]
        }
    ],
    "protected": False,
    "realmAuthorization": {
        "permissions": [
            {
                "artifact": {
                    "type": "TECHNOLOGY_CATALOG"
                },
                "role": "ROLE_ACCESS"
            }
        ]
    }
}
```

--------------------------------

### Create a New Project

Source: https://github.com/saagie/api-saagie/blob/master/docs/Projects/index.md

Use this method to create a new project on the Saagie platform. You can specify allowed job and app technologies, as well as group roles. If no technologies are specified, the default Saagie catalog technologies will be used.

```python
>>> saagie_client.projects.create(
...     name="Project_A",
...     groups_and_roles=[{"my_group": "Manager"}],
...     jobs_technologies_allowed={"saagie": ["python", "spark"]},
...     apps_technologies_allowed={"saagie": ["Jupyter Notebook"]}
... )
{
    'createProject': {
        'id': '09515109-e8d3-4ed0-9ab7-5370efcb6cb5',
        'name': 'Project_A',
        'creator': 'toto.tata'
    }
}
```

--------------------------------

### Get Job Instance

Source: https://github.com/saagie/api-saagie/blob/master/docs/Jobs/index.md

Retrieves information about a specific job instance using its unique job instance ID.

```APIDOC
## get_instance(job_instance_id: str, pprint_result: bool | None = None)

### Description
Get the given job instance

### Method
```python
get_instance(job_instance_id: str, pprint_result: bool | None = None)
```

### Parameters
#### Path Parameters
- **job_instance_id** (str) - Required - UUID of your job instance (see README on how to find it)

#### Query Parameters
- **pprint_result** (bool) - Optional - Whether to pretty print the result of the query, default to saagie_api.pprint_global

### Response
#### Success Response (200)
- **instance information** (dict) - Dict of instance information

### Return type
dict
```

--------------------------------

### Create a New Saagie Job

Source: https://github.com/saagie/api-saagie/blob/master/docs/Jobs/index.md

Creates a new job in a specified project with various configuration options. Requires gql>=3.0.0. Ensure the `job_name` does not already exist in the project.

```python
saagie_api.jobs.create(job_name='my_job', project_id='my_project_uuid', file='path/to/job/file.py', description='My job description', category='Processing', technology='python', runtime_version='3.10', command_line='python {file} arg1 arg2', cron_scheduling='0 0 * * *', schedule_timezone='UTC', resources={'cpu': {'request': 0.5, 'limit': 2.6}, 'memory': {'request': 1.0}}, emails=['user@example.com'], status_list=['FAILED', 'SUCCEEDED'], source_url='http://github.com/my_repo/commit/12345', docker_info={'image': 'my_image', 'dockerCredentialsId': 'MY_CREDENTIALS_ID'})
```

--------------------------------

### Run Job

Source: https://github.com/saagie/api-saagie/blob/master/docs/Jobs/index.md

Initiates the execution of a specified job.

```APIDOC
## RUN JOB

### Description
Runs a job using its unique identifier.

### Method
POST

### Endpoint
/jobs/{job_id}/run

### Parameters
#### Path Parameters
- **job_id** (string) - Required - The unique identifier of the job to run.

### Request Example
```python
saagieapi.jobs.run(job_id="f5fce22d-2152-4a01-8c6a-4c2eb4808b6d")
```

### Response
#### Success Response (200)
- **runJob** (object) - Contains information about the job run.
  - **id** (string) - The ID of the job instance.
  - **status** (string) - The initial status of the job run.
```

--------------------------------

### Get App ID

Source: https://github.com/saagie/api-saagie/blob/master/docs/Apps/index.md

Retrieves the unique identifier (UUID) of an application using its name and the project name it belongs to.

```APIDOC
## get_id(app_name: str, project_name: str) -> str

### Description
Get the app id with the app name and project name

### Parameters
* **app_name** (*str*) – Name of your app
* **project_name** (*str*) – Name of your project

### Returns
App UUID

### Return type
str

### Examples
```pycon
>>> saagieapi.apps.get_id(
...     app_name="my-app",
...     project_name="my-project"
... )
"860b8dc8-e634-4c98-b2e7-f9ec32ab4771"
```
```

--------------------------------

### Get Project Rights

Source: https://github.com/saagie/api-saagie/blob/master/docs/Projects/index.md

Retrieves the rights associated with a specific project. This is useful for understanding user permissions for a project.

```python
>>> saagieapi.projects.get_rights(project_id="8321e13c-892a-4481-8552-5be4d6cc5df4")
{
    'rights': [
        {
            'name': 'manager_group',
            'role': 'ROLE_PROJECT_MANAGER',
            'isAllProjects': True
        },
        {
            'name': 'my_group',
            'role': 'ROLE_PROJECT_MANAGER',
            'isAllProjects': False
        }
    ]
}
```