# API call blueprint

The time to run a calculation using the OLI API cannot be predicted accurately and also some calculations may take longer to compute than others. Hence, a polling mechanism is required to retrieve the result of each calculation. The steps for this mechanism is described below.

1. Send a **GET/POST** request to the specific URL
2. If the request was successful(status:200), the JSON response back will contain a link to the results and status of the computation. The status can be **IN QUEUE/IN PROGRESS**
3. Keep polling the results link with a **GET** request until status of the response changes to **PROCESSED/FAILED/ERROR**
4.  if status is **PROCESSED**, then response will also contain the result of the computation

### Here is an example for an isothermal flash call

## Isothermal flash \[1st request]

<mark style="color:green;">`POST`</mark> `https://api.olisystems.com/engine/flash/{dbs_file_id}/isothermalFlash`

&#x20;The first request to initiate an isothermal flash calculation

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |
| Content-Type  | string | application/json       |

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

```
{
	"code": 200,
	"data": {
		"file_id": "dee854a6-59db-487d-ad08-a20dee691133",
		"jobId": "f6b3375e-cd0f-4ace-a5ee-71e047b76754",
		"resultsLink": "https://api.olisystems.com/result/flash/f6b3375e-cd0f-4ace-a5ee-71e047b76754?context=engine",
		"status": "IN PROGRESS"
	},
	"message": "Process execution started Successfully",
	"status": "SUCCESS"
}
```

{% endtab %}
{% endtabs %}

### Response description

| field            | description                                                     |
| ---------------- | --------------------------------------------------------------- |
| code             | HTTP response status code                                       |
| data.file\_id    | the dbs file reference identifier                               |
| data.jobId       | the current request job identifier                              |
| data.resultsLink | the https endpoint to poll to get the final result              |
| data.status      | current status of the job                                       |
| message          | message describing the request                                  |
| status           | status of the current request, can be **SUCCESS** or **FAILED** |

{% hint style="warning" %}
**access\_token** in the request authorization header is obtained as shown here.

**db\_file\_id** is the id of the dbs file, you can obtain it [here](/uploading-oli-files.md).
{% endhint %}

## Result of computation \[2nd request and onwards]

<mark style="color:blue;">`GET`</mark> `https://api.olisystems.com/result/flash/{jobId}?context=engine`

URL contains the result of the computation if status is processed

#### Headers

| Name          | Type   | Description            |
| ------------- | ------ | ---------------------- |
| Authorization | string | Bearer {access\_token} |
| Content-Type  | string | application/json       |

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

```
{
    "code": 200, 
    "data": {
        "result": {
          ...
          }
    }, 
    "message": "Results returned successfully", 
    "resultsLink": "https://devapi.olisystems.com/result/flash/fbce59ee-f31e-447b-b450-ba5b0d0a1a99?context=engine", 
    "status": "PROCESSED"
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
status can be **IN QUEUE**, **IN PROGRESS**, **PROCESSED, FAILED** or **ERROR**

if status = **IN QUEUE**/**IN PROGRESS**, keep polling the endpoint in resultsLink

if status = **PROCESSED**, result should be in **data.result**

if status = **FAILED**, computation failure. error will be be in **data.error**

if status = **ERROR**, a system error occurred
{% endhint %}

#### Example chain of request responses

```javascript
// 1st Response
{
  "code": 200, 
  "data": {
    "fileId": "b60c97de-3486-4165-8589-d9885d14a382", 
    "jobId": "318e35c7-609b-466f-876f-e872a5b0a4a0", 
    "resultsLink": "https://api.olisystems.com/result/flash/318e35c7-609b-466f-876f-e872a5b0a4a0?context=engine", 
    "status": "IN PROGRESS"
  }, 
  "message": "Process execution started Successfully", 
  "status": "SUCCESS"
}

// 2nd response on GET resultsLink
{
  "code": 200, 
  "data": {}, 
  "message": "Results returned successfully", 
  "resultsLink": "https://api.olisystems.com/result/flash/318e35c7-609b-466f-876f-e872a5b0a4a0?context=engine", 
  "status": "IN PROGRESS"
}

// 3rd request on GET resultsLink (still in progress)
{
  "code": 200, 
  "data": {}, 
  "message": "Results returned successfully", 
  "resultsLink": "https://api.olisystems.com/result/flash/318e35c7-609b-466f-876f-e872a5b0a4a0?context=engine", 
  "status": "IN PROGRESS"
}

// 4th request on GET resultsLink (processed!), result in data.result
{
  "code": 200, 
  "data": {
    "result": {
      ...
      }
    },
  "message": "Results returned successfully",
  "status": "PROCESSED"
}
```

{% hint style="warning" %}
Presence of the **data.result** object signifies that results are available. if **data.error** object is present, then this means that the computation has failed
{% endhint %}


---

# 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/group1/api-functions/api-call-blueprint.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.