wiki.pengtools.com - User contributions [en]

PVT API

2026-07-22T14:31:59Z

MishaT: /* Python Quick Start */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]]. [[File:pengtools_PVT_API.png|center|600px| PVT REST API]]

==Python Quick Start==

The notebook demonstrates how to call the pengtools PVT calculator over the HTTP API:

* Configuration — PENGTOOLS_API_BASE and PENGTOOLS_API_KEY
* Helpers — requests session with Bearer token and parsing of {success, data} envelope
* Synchronous calculation — POST /pvt-calculator/calc
* Plots — render every curve from the plots block
* Error handling — 401 / 422

Create a key in the accounts portal: [https://accounts.pengtools.com accounts.pengtools.com] → profile → API keys.
Contact us at support@pengtools.com to activate your API trial license.

The notebook is self-contained. Download it here: [[Media:pvt_api.ipynb|pvt_api.ipynb]]

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

File:Pvt api.ipynb

2026-07-22T14:30:29Z

MishaT: PVT Calculator — API usage example This notebook shows how to call the pengtools PVT calculator over the HTTP API.

PVT Calculator — API usage example
This notebook shows how to call the pengtools PVT calculator over the HTTP API.

PVT API

2026-07-22T13:35:09Z

MishaT: /* Python Quick Start */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]]. [[File:pengtools_PVT_API.png|center|600px| PVT REST API]]

==Python Quick Start==

The notebook demonstrates how to call the pengtools PVT calculator over the HTTP API:

* Configuration — PENGTOOLS_API_BASE and PENGTOOLS_API_KEY
* Helpers — requests session with Bearer token and parsing of {success, data} envelope
* Synchronous calculation — POST /pvt-calculator/calc
* Plots — render every curve from the plots block
* Error handling — 401 / 422

Create a key in the accounts portal: [https://accounts.pengtools.com accounts.pengtools.com] → profile → API keys.
Contact us at support@pengtools.com to activate your API trial license.

The notebook is self-contained.

[[File:pvt_api.ipynb]]

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-22T13:34:54Z

MishaT: /* Python Quick Start */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]]. [[File:pengtools_PVT_API.png|center|600px| PVT REST API]]

==Python Quick Start==

The notebook demonstrates how to call the pengtools PVT calculator over the HTTP API:

* Configuration — PENGTOOLS_API_BASE and PENGTOOLS_API_KEY
* Helpers — requests session with Bearer token and parsing of {success, data} envelope
* Synchronous calculation — POST /pvt-calculator/calc
* Plots — render every curve from the plots block
* Error handling — 401 / 422

Create a key in the accounts portal: [https://accounts.pengtools.com accounts.pengtools.com] → profile → API keys.
Contact us at support@pengtools.com to activate your API trial license.

The notebook is self-contained and covers PVT only.

[[File:pvt_api.ipynb]]

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-22T13:33:53Z

MishaT: /* Python Quick Start */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]]. [[File:pengtools_PVT_API.png|center|600px| PVT REST API]]

==Python Quick Start==

The notebook demonstrates how to call the pengtools PVT calculator over the HTTP API:

* Configuration — PENGTOOLS_API_BASE and PENGTOOLS_API_KEY
* Helpers — requests session with Bearer token and parsing of {success, data} envelope
* Synchronous calculation — POST /pvt-calculator/calc
* Plots — render every curve from the plots block
* Error handling — 401 / 422

Create a key in the accounts portal: [https://accounts.pengtools.com accounts.pengtools.com] → profile → API keys.

The notebook is self-contained and covers PVT only.

[[File:pvt_api.ipynb]]

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

Category:API

2026-07-22T13:01:22Z

MishaT: /* Support */

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com]. [[File:pengtools_REST_API.png|center|right|600px| pengtools REST API|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.
# Contact us at [mailto:support@pengtools.com support@pengtools.com] to activate your API trial license.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429.

==Quickstart==

==Support==

For questions or issues contact us at [mailto:support@pengtools.com support@pengtools.com].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-22T13:00:15Z

MishaT: /* Getting a key */

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com]. [[File:pengtools_REST_API.png|center|right|600px| pengtools REST API|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.
# Contact us at [mailto:support@pengtools.com support@pengtools.com] to activate your API trial license.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429.

==Quickstart==

==Support==

For questions or issues contact us at [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-22T13:00:04Z

MishaT: /* Getting a key */

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com]. [[File:pengtools_REST_API.png|center|right|600px| pengtools REST API|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.
# Contact us at [mailto:support@pengtools.com support@pengtools.com] to activate your API trial license.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429.

==Quickstart==

==Support==

For questions or issues contact us at [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-22T04:27:10Z

MishaT:

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com]. [[File:pengtools_REST_API.png|center|right|600px| pengtools REST API|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429.

==Quickstart==

==Support==

For questions or issues contact us at [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

PVT API

2026-07-22T04:26:43Z

MishaT:

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]]. [[File:pengtools_PVT_API.png|center|600px| PVT REST API]]

==Python Quick Start==

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-22T04:25:59Z

MishaT:

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]]. [[File:pengtools_PVT_API.png|thumb|600px| PVT REST API]]

==Python Quick Start==

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-22T04:25:48Z

MishaT:

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].[[File:pengtools_PVT_API.png|thumb|600px| PVT REST API]]

==Python Quick Start==

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-22T04:24:26Z

MishaT:

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].
[[File:pengtools_PVT_API.png|thumb|600px| PVT REST API]]

==Python Quick Start==

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-22T04:24:15Z

MishaT:

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].
[[File:pengtools_PVT_API.png|thumb|right|300px| PVT REST API]]

==Python Quick Start==

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

File:Pengtools PVT API.png

2026-07-22T04:23:02Z

MishaT: The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using industry-standard correlations. The API returns pressure-dependent property curves, reservoir-condition values, and complete calculation tables.

The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using industry-standard correlations. The API returns pressure-dependent property curves, reservoir-condition values, and complete calculation tables.

PVT API

2026-07-22T04:21:38Z

MishaT:

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].
[[File:pengtools_PVT_API.png|thumb|right|300px| PVT REST API|right]]

==Python Quick Start==

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

Category:API

2026-07-20T11:30:20Z

MishaT:

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com].

[[File:pengtools_REST_API.png|thumb|right|300px| pengtools REST API|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429.

==Quickstart==

==Support==

For questions or issues contact us at [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

File:Pengtools REST API.png

2026-07-20T11:29:07Z

MishaT: REST APIs for Petroleum Engineering Programmatic access to the pengtools engineering modules for calculations, automation and optimization.

REST APIs for Petroleum Engineering
Programmatic access to the pengtools engineering modules for calculations, automation and optimization.

Category:API

2026-07-16T10:54:49Z

MishaT: /* REST APIs for Petroleum Engineering */

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com].

[[File:pengtools_REST_API.png|thumb|right|300px| pengtools RESt API|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429.

==Quickstart==

==Support==

For questions or issues contact us at [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-15T12:49:16Z

MishaT: /* Support */

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com].

[[File:EPPortal.png|thumb|right|300px|link=https://ep.pengtools.com/| E&P Portal|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429.

==Quickstart==

==Support==

For questions or issues contact us at [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-15T12:48:07Z

MishaT: /* Quickstart */

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com].

[[File:EPPortal.png|thumb|right|300px|link=https://ep.pengtools.com/| E&P Portal|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429.

==Quickstart==

==Support==

For questions or issues, contact [[Support]] or visit our [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-15T12:45:49Z

MishaT: /* Getting Started */

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com].

[[File:EPPortal.png|thumb|right|300px|link=https://ep.pengtools.com/| E&P Portal|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429.

==Quickstart==

1. [[Authentication]] - API key setup
2. [[API Reference]] - Endpoint documentation
3. [[Rate Limits]] - Usage policies

==Support==

For questions or issues, contact [[Support]] or visit our [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-15T12:44:59Z

MishaT: /* Response envelope */

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com].

[[File:EPPortal.png|thumb|right|300px|link=https://ep.pengtools.com/| E&P Portal|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429.

==Getting Started==

1. [[Authentication]] - API key setup
2. [[API Reference]] - Endpoint documentation
3. [[Rate Limits]] - Usage policies

==Support==

For questions or issues, contact [[Support]] or visit our [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-15T12:43:59Z

MishaT: /* Getting a key */

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com].

[[File:EPPortal.png|thumb|right|300px|link=https://ep.pengtools.com/| E&P Portal|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429. See the error reference for details.

==Getting Started==

1. [[Authentication]] - API key setup
2. [[API Reference]] - Endpoint documentation
3. [[Rate Limits]] - Usage policies

==Support==

For questions or issues, contact [[Support]] or visit our [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-15T12:43:45Z

MishaT: /* Getting a key */

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com].

[[File:EPPortal.png|thumb|right|300px|link=https://ep.pengtools.com/| E&P Portal|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at [https://accounts.pengtools.com accounts.pengtools.com].
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429. See the error reference for details.

==Getting Started==

1. [[Authentication]] - API key setup
2. [[API Reference]] - Endpoint documentation
3. [[Rate Limits]] - Usage policies

==Support==

For questions or issues, contact [[Support]] or visit our [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-15T12:40:53Z

MishaT:

__TOC__

==REST APIs for Petroleum Engineering==

The pengtools [[:Category:pengtools | API]] gives programmatic access to the engineering calculators that power [https://www.pengtools.com www.pengtools.com].

[[File:EPPortal.png|thumb|right|300px|link=https://ep.pengtools.com/| E&P Portal|right]]

==Available APIs==

* [[:PVT_API|PVT API]] - Fluid properties calculator

==Base URL==

<pre>https://api.pengtools.com/</pre>

Endpoints are addressed as <base>/<resource>/<action>, e.g. <pre>https://api.pengtools.com/pvt-calculator/calc</pre>. All examples below use this base URL.

==Authentication==

Every request must include an API key as a Bearer token:

<pre>Authorization: Bearer <api_key></pre>

A key is a single opaque token. It is stored only as a salted hash on the server, so the plaintext is shown once, at creation time, and cannot be recovered afterwards.

===Getting a key===

Manage your keys in the accounts portal:

# Sign in at accounts.pengtools.com.
# Open the API keys section of your profile.
# Click Create to issue a new key, optionally giving it a name.

The new token is displayed once, right after creation. Copy it immediately and store it as a secret (environment variable, secrets manager). If you lose it, revoke the key on the same page and create a new one. The page also lists your existing keys (without the plaintext) and lets you revoke any of them.

A request with no key, or an invalid/revoked key, returns HTTP 401.

==Response envelope==

Every JSON response is wrapped in a uniform envelope:

<pre>
{ "success": true, "data": { "...": "..." } }
{ "success": false, "data": { "errors": { "...": "..." } } }
</pre>

success mirrors the HTTP status (2xx → true). Validation problems return 422, rate-limit rejections return 429. See the error reference for details.

==Getting Started==

1. [[Authentication]] - API key setup
2. [[API Reference]] - Endpoint documentation
3. [[Rate Limits]] - Usage policies

==Support==

For questions or issues, contact [[Support]] or visit our [https://www.pengtools.com/contact contact page].

[[Category:APT]]

{{#seo:
|title=Petroleum Engineering API Documentation
|titlemode= replace
|keywords=petroleum engineering API, PVT API, nodal analysis API, bottomhole pressure calculation API developer docs, pengtools API, REST API
|description=Programmatic access to pengtools petroleum engineering software: PVT, PQplot, sPipe, optiFrac, fracDesign, pumpDesign.
}}

Category:API

2026-07-15T11:07:07Z

MishaT: /* Petroleum Engineering API */

PVT API

2026-07-15T08:07:59Z

MishaT: /* Phyton Quick Start */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Python Quick Start==

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T08:07:24Z

MishaT:

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Phyton Quick Start==

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T08:04:33Z

MishaT: /* Synchronous request */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* <code>plots</code> — property curves
* <code>solution</code> — single-point reservoir-condition values
* <code>results</code> — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T08:04:04Z

MishaT: /* Synchronous request */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys (see Units):
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T08:03:14Z

MishaT: /* Endpoints */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an <code>api_task</code> row that is picked up by the <code>CalcDaemon</code> worker; you then poll <code>status</code> and fetch <code>output-data</code> . The async job runs the same <code>calculatePvt()</code> code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T08:02:23Z

MishaT: /* Endpoints */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use <code>/calc</code> (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use <code>/calc-async</code> only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T08:01:22Z

MishaT: /* Example */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use /calc (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use /calc-async only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
<pre>
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}
</pre>

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T08:01:04Z

MishaT: /* Units */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use /calc (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use /calc-async only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

====Example====
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T08:00:48Z

MishaT: /* Units */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use /calc (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use /calc-async only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code> a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):

* METRIC - Metric system
* FIELD - Field system

Example:
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T08:00:34Z

MishaT: /* Units */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use /calc (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use /calc-async only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

<code>unit_system</code>

a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):
* METRIC - Metric system
* FIELD - Field system

Example:
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T08:00:03Z

MishaT: /* Synchronous request */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use /calc (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use /calc-async only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
<pre>
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}
</pre>
On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

unit_system

a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):
* METRIC - Metric system
* FIELD - Field system

Example:
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T07:59:30Z

MishaT: /* HTTP status codes */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use /calc (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use /calc-async only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}

On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

unit_system

a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):
* METRIC - Metric system
* FIELD - Field system

Example:
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T07:58:49Z

MishaT: /* HTTP status codes */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use /calc (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use /calc-async only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}

On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

unit_system

a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):
* METRIC - Metric system
* FIELD - Field system

Example:
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

===429 - rate limiting===
Limits are per API key over a 60‑second window, and the cap depends on the license tier that grants access to the <code>pvtCalculator</code> module.

==Asynchronous flow==

<pre>
POST /pvt-calculator/calc-async → { "token": "<token>" }
GET /pvt-calculator/<token>/status → { "status": <code>, "progress": <number> }
GET /pvt-calculator/<token>/output-data → { plots, solution, results }
</pre>

<code>status</code> is returned as a numeric code (the raw api_task.status value), not a string:

{| class="wikitable"
|-
! Code !! Meaning
|-
| 1 || CREATED
|-
| 2 || IN_PROGRESS
|-
| 3 || ERROR
|-
| 4 || STOPPED
|-
| 5 || SUCCESS
|}

A job cycles 1 → 2 → 5 (or 3 / 4). Poll <code>status</code> until it reaches a terminal code (3, 4, 5), then fetch <code>output-data</code> when it is 5. The <code>CalcDaemon </code>worker must be running for jobs to progress.

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T07:54:42Z

MishaT: /* HTTP status codes */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use /calc (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use /calc-async only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}

On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

unit_system

a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):
* METRIC - Metric system
* FIELD - Field system

Example:
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

===422 - validation and calculation errors===
Field validation errors are keyed by attribute:
{ "success": false, "data": { "errors": { "temperature": ["Temperature must be no less than 529.47."] } } }
Errors raised while loading the body or running the calculation (e.g. an unknown <code>defaultFluidType</code>, or a physical guard inside <code>calculatePvt()</code>) come back as a flat list:
{ "success": false, "data": { "errors": ["Invalid input: Wrong default fluid type"] } }

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T07:52:37Z

MishaT:

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use /calc (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use /calc-async only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}

On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

unit_system

a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):
* METRIC - Metric system
* FIELD - Field system

Example:
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>

==HTTP status codes==
{| class="wikitable"
|-
! Status !! Meaning !! Body (data)
|-
| 200 || Success || { plots, solution, results }
|-
| 401 || Missing or invalid API key || Yii error payload
|-
| 404 || Unknown async token || Yii error payload
|-
| 422 || Validation / calculation error || { "errors": … }
|-
| 429 || Rate limit exceeded || error message
|}

[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T07:49:41Z

MishaT: /* Response format */

__TOC__

==PVT API==
The PVT calculator models reservoir fluid properties (oil, gas, water) over a pressure range using various correlations, and returns property curves (plots), single‑point reservoir‑condition values (solution), and a stepped property table (results) available in [[:Category:PVT|PVT calculator]] of the [[:Category: Pengtools | pengtools]].

==Endpoints==
All endpoints require the Authorization: Bearer <api_key> header and are subject to rate limiting. The response envelope is always { "success": <bool>, "data": <payload> }

{| class="wikitable"
|-
! Method !! Path !! Purpose
|-
| POST || /pvt-calculator/calc || Synchronous — compute and return the result in the same request
|-
| POST || /pvt-calculator/calc-async || Asynchronous — enqueue a job, return a {token}
|-
| GET || /pvt-calculator/{token}/status || Job status and progress
|-
| GET || /pvt-calculator/{token}/output-data || Job result (same shape as the sync data)
|-
| GET || /pvt-calculator/{token}/input-data || The input the job was created with
|-
| POST || /pvt-calculator/{token}/start || Reset and re-run the job
|-
| POST || /pvt-calculator/{token}/stop || Stop a running job
|-
| DELETE || /pvt-calculator/{token} || Delete the job
|}

Use /calc (synchronous) for normal interactive requests — a single PVT model computes in well under a second and the result comes back in the HTTP response.

Use /calc-async only for batch/heavy workloads where you would rather not hold an open HTTP connection. The async path enqueues an api_task row that is picked up by the CalcDaemon worker; you then poll status and fetch output-data. The async job runs the same calculatePvt() code as the sync endpoint, so the result is identical for identical input.

==Synchronous request==

POST /pvt-calculator/calc

The request body is a JSON object containing PVT calculator attributes plus two optional unit-control keys:
{
"unit_system": "RU",
"defaultFluidType": "OIL",
"maximumPressure": 300,
"reservoirPressure": 300,
"temperature": 90,
"pBubbleInitial": 200,
"rsbInitial": 60,
"isRsbUsedForPb": true,
"sgOil": 0.85,
"sgGas": 0.75,
"sgWater": 1.0
}

On success the endpoint returns HTTP 200 with:

{ "success": true, "data": { "plots": {},"solution": {}, "results": {} } }

Where <code>data</code> carries:
* plots — property curves
* solution — single-point reservoir-condition values
* results — stepped property table

==Units==

Input field names (e.g., maximumPressure, temperature) carry no unit. The unit system determines how values are interpreted.

unit_system

a shortcut that applies a whole preset of units. Accepted values (case‑insensitive):
* METRIC - Metric system
* FIELD - Field system

Example:
{
"unit_system": "METRIC",
"maximumPressure": 300,
"temperature": 90
}

===Attribute units===

{| class="wikitable"
|-
! Field !! METRIC !! FIELD
|-
| maximumPressure || ATM || PSIA
|-
| minimumPressure || ATM || PSIA
|-
| reservoirPressure || ATM || PSIA
|-
| pBubbleInitial || ATM || PSIA
|-
| temperature || CELSIUS || FAHRENHEIT
|-
| rsbInitial || M3_PER_M3 || SCF_PER_BBL
|-
| sgOil || SPECIFIC_GRAVITY || API
|-
| sgGas || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|-
| sgWater || SPECIFIC_GRAVITY || SPECIFIC_GRAVITY
|}

==Input parameter specification==

Ranges below are expressed in internal units (the units the validator sees), with common METRIC/FIELD equivalents for convenience.

{| class="wikitable"
|-
! Field !! Required !! Internal unit !! Range (internal) !! METRIC !! FIELD !! Notes
|-
| defaultFluidType || yes || — || OIL or GAS || — || — || Selects the primary fluid path. WATER is only valid inside forFluid.
|-
| maximumPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Upper bound of the pressure sweep.
|-
| minimumPressure || no (default 14.6) || PSIA || 14.6 … 10000 || ≈ 1.0 … 680 ATM || 14.6 … 10000 psi || Lower bound of the sweep; must be ≤ maximumPressure.
|-
| reservoirPressure || yes || PSIA || 25 … 10000 || ≈ 1.7 … 680 ATM || 25 … 10000 psi || Reservoir-condition pressure for solution.
|-
| temperature || yes || RANKIN || 529.47 … 851.67 || ≈ 21 … 200 °C || ≈ 70 … 392 °F || Reservoir-condition temperature for solution.
|-
| pBubbleInitial || yes || PSIA || 0 … 20000 || ≈ 0 … 1361 ATM || 0 … 20000 psi || Initial bubble point. See isRsbUsedForPb.
|-
| rsbInitial || yes (when OIL) || M3_PER_M3 || > 0 || m³·m⁻³ || scf/bbl || Solution GOR at bubble point.
|-
| sgOil || yes || SPECIFIC_GRAVITY || 0.75 … 0.99 || 0.75 … 0.99 SG || ≈ 11.4 … 57.2 °API || Oil specific gravity. US system accepts API.
|-
| sgGas || yes || SPECIFIC_GRAVITY || 0.55 … 1.8 || 0.55 … 1.8 SG || 0.55 … 1.8 SG || Gas specific gravity (air = 1).
|-
| sgWater || yes || SPECIFIC_GRAVITY || 0.9 … 1.2 || 0.9 … 1.2 SG || 0.9 … 1.2 SG || Water specific gravity.
|-
| isRsbUsedForPb || no (default false) || bool || true / false || — || — || true: derive bubble point from rsbInitial. false: derive GOR from pBubbleInitial.
|-
| forFluid || no (default all) || — || subset of OIL,GAS,WATER || — || — || Which fluids to compute.
|-
| needPlots || no (default true) || bool || true / false || — || — || Include the plots block.
|-
| needSolution || no (default true) || bool || true / false || — || — || Include the solution block.
|-
| needResults || no (default true) || bool || true / false || — || — || Include the results block.
|}

===Notes===
For an oil model, both <code>pBubbleInitial</code> and <code>rsbInitial</code>are required; <code>isRsbUsedForPb</code> decides which one is the input and which is derived.

==Response format==
On success, data contains up to three blocks, gated by <code>needPlots / needSolution / needResults</code>. Each block is keyed by fluid (<code>OIL, GAS, WATER</code>) — only the fluids in <code>forFluid</code> (and, for oil curves, only when <code>defaultFluidType is OIL</code>) are present.

===Plots - property curves===
Each fluid maps curve names to an array of [pressure, value] pairs, one pair per pressure step (200 steps by default). The pressure axis is in the output pressure unit (see Units section).

{| class="wikitable"
|-
! Fluid !! Curves
|-
| OIL || Rs, density, fvf, viscosity, tension, compressibility
|-
| GAS || ZFactor, densitygas, fvfgas, viscositygas, compressibilitygas
|-
| WATER || densitywater, fvfwater, viscositywater, compressibilitywater, tensionwater
|}

====Example====

<pre>
"plots": {
"OIL": {
"Rs": [[14.6, 0.0], [36.4, 5.1], "…", [4351.13, 200.0]],
"fvf": [[14.6, 1.02], "…"],
"density": [[14.6, 812.4], "…"]
}
}
</pre>

===Solution - reservoir‑condition values===
Single scalar values evaluated at reservoir conditions.

{| class="wikitable"
|-
! Fluid !! Keys
|-
| OIL || solution_pBubble, solution_rsb, solution_Rs, solution_compressibility, solution_density, solution_fvf, solution_deadOilViscosity, solution_viscosity, solution_tension
|-
| GAS || solution_ZFactor, solution_compressibilitygas, solution_densitygas, solution_fvfgas, solution_viscositygas
|-
| WATER || solution_compressibilitywater, solution_densitywater, solution_fvfwater, solution_viscositywater, solution_tensionwater
|}

====Example====
<pre>
"solution": {
"OIL": {
"solution_pBubble": 115.0,
"solution_rsb": 60.0,
"solution_density": 756.0,
"solution_fvf": 1.197
}
}
</pre>

===Results - stepped table===
Each fluid maps to a list of rows. The first row is standard conditions; the next nine rows are stepped pressures between the bubble point (oil) or p/2 (gas/water) and the maximum pressure. Each row is a positional array with these columns:

{| class="wikitable"
|-
! Fluid !! Columns (in order)
|-
| OIL || pressure, Rs, density, fvf, viscosity, temperature, compressibility, tension
|-
| GAS || pressure, ZFactor, densitygas, fvfgas, viscositygas, temperature, compressibilitygas
|-
| WATER || pressure, compressibilitywater, densitywater, fvfwater, viscositywater, temperature, tensionwater
|}

<pre>
"results": {
"OIL": [
[1.0, 0.0, 845.0, 1.01, 2.1, 20.0, 0.00012, 30.5],
[12.8, 22.0, 812.4, 1.08, 1.6, 90.0, 0.00018, 12.1],
"… 8 more rows …"
]
}
</pre>
[[Category:API]]

{{#seo:
|title=PVT API Documentation | Petroleum Engineering Software
|titlemode= replace
|keywords=PVT API, petroleum engineering API, fluid properties API, REST API, developer documentation, pengtools API
|description=REST API documentation for PVT fluid properties calculator. Endpoints, authentication, and data models for programmatic access to oil, gas, and water property calculations.
}}

PVT API

2026-07-15T07:47:51Z

MishaT: /* Response format */

PVT API

2026-07-15T07:46:13Z