# EVA REST API

Source: https://developers.novilabs.com/eva/api/

> Pull Novi EVA field values, production and forecasts for a list of wells, and write your organization's columns and shapefiles into EVA.

Pull field values, production and forecasts for a list of wells into scripts, dataframes and load jobs, in the order you ask for them. You can also write your organization's own columns and upload shapefiles.

## Base URL

```text
https://api.novilabs.com
```

> **Preview:**
> The EVA REST API is in preview. `api.novilabs.com` is not live yet; access details come with its release.

All endpoints are under `/v1`. OpenAPI 3.1 document: [eva.json](https://developers.novilabs.com/openapi/eva.json).

## Authentication

Create a Developer API Token on EVA's **Organization Settings** page and send it in the `x-api-key` header. It acts for your EVA organization: keep it out of source code and load it from the environment.

```bash
export NOVI_EVA_API_KEY="<your Developer API Token>"
```

It is not a Novi API token, and the [EVA MCP server](https://developers.novilabs.com/eva/mcp/) does not take it.

## Endpoints

| Method | Path | What it does |
|---|---|---|
| GET | `/v1/data/fields` | List the fields you can request, optionally for one `group` |
| POST | `/v1/data` | Field values for up to 50,000 wells |
| POST | `/v1/production` | Production history and forecast for up to 1,000 wells |
| GET | `/v1/columns/org-defined-columns` | List your organization's columns |
| POST | `/v1/columns/org-defined-columns` | Create an organization column |
| GET | `/v1/columns/org-defined-columns/{id}` | Get one column with its values |
| PUT | `/v1/columns/org-defined-columns/{id}` | Update a column and its values |
| POST | `/v1/shapefile/upload` | Upload a shapefile to your organization |

## Quickstart

### 1. Find field keys

Groups: Header, Dates, Geology, Well Design, Frac Data, Performance and Forecast. Leave out `group` for every field.

```bash
curl -s "https://api.novilabs.com/v1/data/fields?group=Header" \
  -H "x-api-key: $NOVI_EVA_API_KEY"
```

Each entry has `field`, the key you request (such as `Header.ResourcePlay`), and `fieldName`, its display name.

### 2. Get values for your wells

  **curl**
```bash
curl -s https://api.novilabs.com/v1/data \
  -H "x-api-key: $NOVI_EVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wellList": ["100091802103W500", "100111403204W500"],
    "fields": ["Header.ResourcePlay", "Header.Status", "Dates.Vintage_Year"]
  }'
```
  
  **Python**
```python
import os

import requests

response = requests.post(
    "https://api.novilabs.com/v1/data",
    headers={"x-api-key": os.environ["NOVI_EVA_API_KEY"]},
    json={
        "wellList": ["100091802103W500", "100111403204W500"],
        "fields": ["Header.ResourcePlay", "Header.Status", "Dates.Vintage_Year"],
    },
    timeout=120,
)
response.raise_for_status()
for well in response.json():
    print(well["uwid"], well["data"])
```
  

One entry per well comes back, in request order, with your identifiers as sent and `data` in the order of `fields`:

```json
[
  { "uwid": "100091802103W500", "data": ["<Header.ResourcePlay>", "<Header.Status>", "<Dates.Vintage_Year>"] },
  { "uwid": "100111403204W500", "data": ["<Header.ResourcePlay>", "<Header.Status>", "<Dates.Vintage_Year>"] }
]
```

- `"n/a"`: not available for that well. A well not found returns `"data": ["n/a"]`.
- `"Subscription Required"`: your subscription does not include that value.

Optional `productionSource` picks the production source; `publicDataTrumpingOrder` sets which public source wins per category (`Header`, `Survey`, `Frac`, `Production`) when sources disagree. Values: [OpenAPI document](https://developers.novilabs.com/openapi/eva.json).

### 3. Get production

```bash
curl -s https://api.novilabs.com/v1/production \
  -H "x-api-key: $NOVI_EVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wellList": ["100091807811W600"],
    "productionSource": "GDC",
    "forecastSource": "GDC",
    "includeForecast": false
  }'
```

Each well returns `id`, `history` and `forecast` arrays. `forecast` is empty with `includeForecast: false`; both are empty for a well not found.

## Organization columns

Store your organization's own values per well in EVA, keyed by well identifier.

```bash
curl -s https://api.novilabs.com/v1/columns/org-defined-columns \
  -H "x-api-key: $NOVI_EVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Field",
    "subgroup": "Tests",
    "dataType": "Number",
    "defaultUnit": "bbl",
    "data": { "100091802103W500": 100.1, "100111403204W500": 150.3 }
  }'
```

`dataType` is `Number`, `Text` or `Date`. Other fields: `published`, `canBin`, `canNormalize`, `normalizeByDefault`, `propertyName`, `withinSubgroupOrder`. Update with `PUT /v1/columns/org-defined-columns/{id}`; `GET` on that path returns it with its values.

## Shapefile upload

Send the shapefile's files as `multipart/form-data` parts, each with its file name:

```bash
curl -s https://api.novilabs.com/v1/shapefile/upload \
  -H "x-api-key: $NOVI_EVA_API_KEY" \
  -F "file=@acreage.shp" \
  -F "file=@acreage.shx" \
  -F "file=@acreage.dbf" \
  -F "file=@acreage.prj"
```

## Limits

| Limit | Value |
|---|---|
| Wells per `POST /v1/data` | 50,000 |
| Wells per `POST /v1/production` | 1,000 |
| Request rate | 10 per second on average, bursts up to 30 |
| Requests in flight | 5 |

## Troubleshooting

Errors return JSON with one field, `error`.

| What you see | Meaning | Fix |
|---|---|---|
| `401` `{"error": "Missing x-api-key header"}` | No key was sent | Send the key in the `x-api-key` header |
| `401` `{"error": "Invalid API key"}` | The key is not valid | Check the key, or create a new one on **Organization Settings** |
| `400` `{"error": "Too many wells requested. Limited to 50,000 at a time."}` | Over the well limit on `POST /v1/data` | Split the well list |
| `400` with `Limited to 1000 at a time.` | Over the well limit on `POST /v1/production` | Split the well list |

> **Note:**
> The REST API takes no filters. To ask about a whole basin or play without a well list, use the [EVA MCP server](https://developers.novilabs.com/eva/mcp/) (in preview).
