# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devdocs.olisystems.com/chemistry-model-files/chembuilder-api/getting-started-with-chembuilder.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.