EVA REST 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
Section titled “Base URL”https://api.novilabs.comAll endpoints are under /v1. OpenAPI 3.1 document: eva.json.
Authentication
Section titled “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.
export NOVI_EVA_API_KEY="<your Developer API Token>"It is not a Novi API token, and the EVA MCP server does not take it.
Endpoints
Section titled “Endpoints”| Method | Path | What it does |
|---|---|---|
| GET | / |
List the fields you can request, optionally for one group |
| POST | / |
Field values for up to 50,000 wells |
| POST | / |
Production history and forecast for up to 1,000 wells |
| GET | / |
List your organization’s columns |
| POST | / |
Create an organization column |
| GET | / |
Get one column with its values |
| PUT | / |
Update a column and its values |
| POST | / |
Upload a shapefile to your organization |
Quickstart
Section titled “Quickstart”1. Find field keys
Section titled “1. Find field keys”Groups: Header, Dates, Geology, Well Design, Frac Data, Performance and Forecast. Leave out group for every field.
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
Section titled “2. Get values for your wells”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"] }'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:
[ { "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.
3. Get production
Section titled “3. Get production”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
Section titled “Organization columns”Store your organization’s own values per well in EVA, keyed by well identifier.
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
Section titled “Shapefile upload”Send the shapefile’s files as multipart/form-data parts, each with its file name:
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
Section titled “Limits”| Limit | Value |
|---|---|
Wells per POST / |
50,000 |
Wells per POST / |
1,000 |
| Request rate | 10 per second on average, bursts up to 30 |
| Requests in flight | 5 |
Troubleshooting
Section titled “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. |
Over the well limit on POST / |
Split the well list |
400 with Limited to 1000 at a time. |
Over the well limit on POST / |
Split the well list |