> For the complete documentation index, see [llms.txt](https://devdocs.olisystems.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devdocs.olisystems.com/chemistry-model-files/chembuilder-api/getting-started-with-chembuilder.md).

# Getting Started with ChemBuilder

### Here is an example DBS file generation request.

Here is a request to generate a DBS file using a sample JSON file. The JSON file should list all the required fields.

## Run a sample case using .DBS file

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/channel/dbs`&#x20;

Run **.dbs** file generation&#x20;

#### Headers

| Name                                            | Type   | Description              |
| ----------------------------------------------- | ------ | ------------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer {{access\_token}} |
| Content-Type<mark style="color:red;">\*</mark>  | String | application/json         |

{% tabs %}
{% tab title="200: OK  " %}

```json
{
    "data": {
        "fileName": "testModel.dbs",
        "id": "12345a67e89123" 
    },
    "message": "DBS file generated successfully",
    "status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}

### JSON Request Payload Format:

```json
  {
      "params": {
        "thermodynamicFramework": "MSE (H3O+ ion)",
        "modelName": "testModel",
        "privateDatabanks": []
      "phases": [
        "liquid1",
        "vapor",
        "solid", 
        "liquid2"
      ],
        "inflows": [
            {
                "name": "H2O"
            },
            {
                "name": "NACL"
            }
        ]
    }
}
```

### Field description

<table><thead><tr><th width="251.51898734177217">params</th><th width="98" align="center">required</th><th width="143" align="center">type</th><th>description</th></tr></thead><tbody><tr><td>thermodynamicFramework</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String </td><td><p>OLI Thermodynamic Framework.</p><p><br>Options: <br>Aqueous (H+ ion) <br>MSE-SRK (H3O+ ion) <br>MSE (H3O+ ion)</p></td></tr><tr><td>privateDatabanks</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="274c">❌</span></td><td align="center">Array of String</td><td>Array of Private Data Bank Codes.<br><br>e.g. <br>["COR","CER"]</td></tr><tr><td>modelName </td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">String</td><td>Name of the Generated DBS File in OLI Cloud.</td></tr><tr><td>phases</td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">Array of String</td><td><p></p><p>Array of Strings Defining Included Phases:</p><ul><li>"liquid1"</li><li>"solid"</li><li>"vapor"</li><li>"liquid2"</li></ul></td></tr><tr><td>inflows </td><td align="center"><span data-gb-custom-inline data-tag="emoji" data-code="2714">✔️</span></td><td align="center">Array of Object</td><td><p>The Array of JSON Objects Containing Valid Species Identities:</p><ul><li>{"name": "CO2"}</li><li>{"name": "HSION"}</li></ul></td></tr></tbody></table>

{% hint style="warning" %}
The '**liquid1**' phase must always be included in the 'phases' array.
{% endhint %}

### Example Program Demonstrating DBS Generation Process

> Incorporate the following example in conjunction with the OLIAPI class provided in the [Quickstart example](/quickstart.md).

```python
if __name__ == "__main__":
    oliapi = OLIApi("username", "password")  # TODO : Update username and password
    if oliapi.login():
        # Create a input JSON for .dbs file creation
        dbs_data = {
            "params": {
                "thermodynamicFramework": "MSE (H3O+ ion)",
                "modelName": "testModel",
                "phases": [
                    "liquid1",
                    "vapor",
                    "solid",
                    "liquid2"
                ],
                "inflows": [
                        {
                            "name": "CO2"
                        },
                        {
                            "name": "H2S"
                        },
                        { 
                            "name": "SIO2"
                        }, 
                        { 
                            "name": "BOH3" 
                        }, 
                        {
                            "name": "NAION"
                        }, 
                        { 
                            "name": "KION"
                        }, 
                        { 
                            "name": "CAION"
                        }, 
                        { 
                            "name": "MGION"
                        }, 
                        { 
                            "name": "SRION"
                        }, 
                        { 
                            "name": "BAION"
                        }, 
                        { 
                            "name": "FEIIION"
                        }, 
                        { 
                            "name": "CLION"
                        }, 
                        { 
                            "name": "SO4ION"
                        }, 
                        { 
                            "name": "HCO3ION"
                        }, 
                        { 
                            "name": "HSION"
                        }, 
                        { 
                            "name": "ACETATEION"
                        }
                    ]
            }
        }

        # Invoke the Chemistry Builder Function in the OLI Wrapper.
        result = oliapi.generate_chemistry_file("chemistry-builder", "", dbs_data)
        print(json.dumps(result, indent=2).encode('utf8'))

        chemistry_file_id = result["data"]["id"]
        print(f'chemistry fileid: {chemistry_file_id}')
```

### Response (status = SUCCESS)

```json
{
    "data": {
        "fileName": "testModel.dbs",
        "id": "079e5204-d88f-41d9-a90d-07211c1e4ef1",
        "metadata": {
            "executionTime": {
                "unit": "ms",
                "value": 855.0
            },
            "versionInfo": {
                "fullVersion": "11.5.1.9"
            }
        }
    },
    "message": "DBS file generated successfully",
    "status": "SUCCESS"
}
```

Upon successful generation of the chemistry file, the result output will include the Chemistry file ID, retrievable from the data.id field.

### Save and Reuse the Output Chemistry File ID

The Chemistry Builder saves the chemistry model file on the cloud server upon successful execution, returning a file ID to the user. The file ID format resembles this example: `079e5204-d88f-41d9-a90d-07211c1e4ef1`

Regenerate a chemistry model file only if the new calculation employs a different thermodynamic framework or if there are changes in chemical composition, allowed phases, redox conditions, or kinetics.

{% hint style="info" %}
A chemistry model file can be reused in calculations as long as the chemistry remains unchanged.
{% endhint %}

### Delete Chemistry File

You can delete your DBS files by providing the file ID. For more information, please refer to the '[delete-file](/additional-functions/delete-file.md)' documentation.