Find Wells and Asset IDs

The Platform API exposes wells through both /v2/wells and /v2/assets. They represent synchronized views of the same operational asset, but they return different resource IDs and are designed for different workflows.

Choose the correct endpoint

Endpoint	Use it when	Asset ID for Data API
/v2/wells	You are building a well-focused integration or need well lifecycle fields and direct program, pad, rig, frac-fleet, or drillout-unit relationships. This is the recommended endpoint for new well workflows.	Read data[].attributes.asset_id. The top-level data[].id is the Well record ID and is not the dataset asset ID.
/v2/assets?types[]=well	You need a general search across programs, rigs, and wells; need the legacy parent/child asset hierarchy; or want an exact api_number filter.	Read the top-level data[].id. On this endpoint, that ID is the asset ID used in dataset records.

Do not mix the two IDs

For /v2/wells, use attributes.asset_id in Data API queries. For a well returned by /v2/assets, use the resource's top-level id.

Recommended: find a well with /v2/wells

Use /v2/wells to find wells by name, status, state, company, or operational relationship.

GEThttps://api.corva.ai/v2/wells

Common parameters

Name	Type	Requirement	Description
search	String	Optional	Search by well name.
ids[]	Integer array	Optional	Filter by Platform API well IDs.
asset_id	Integer	Optional	Find a well by dataset asset ID.
company	Integer	Optional	Filter by company ID.
program	Integer	Optional	Filter by program ID.
pad	Integer	Optional	Filter by pad ID.
status[]	String array	Optional	Filter by operational status.
state[]	String array	Optional	Filter by lifecycle state.
visibility	String	Optional	Commonly visible.
fields[]	String array	Optional	Return selected fields such as well.name.
per_page	Integer	Optional	Number of wells per page.
sort	String	Optional	Sort field; defaults to last_active_at.
order	String	Optional	asc or desc; defaults to asc.

The full endpoint supports additional filters. See the maintained Platform API Reference for the verified list and examples.

Example: active drilling wells

cURL

curl --get 'https://api.corva.ai/v2/wells' \
  --header "Authorization: API ${CORVA_API_KEY}" \
  --data-urlencode 'visibility=visible' \
  --data-urlencode 'status[]=active' \
  --data-urlencode 'status[]=paused' \
  --data-urlencode 'state[]=drilling' \
  --data-urlencode 'fields[]=well.name' \
  --data-urlencode 'fields[]=well.asset_id' \
  --data-urlencode 'sort=name' \
  --data-urlencode 'order=asc' \
  --data-urlencode 'per_page=100'

Python

import os
import requests

response = requests.get(
    "https://api.corva.ai/v2/wells",
    headers={"Authorization": f"API {os.environ['CORVA_API_KEY']}"},
    params={
        "visibility": "visible",
        "status[]": ["active", "paused"],
        "state[]": ["drilling"],
        "fields[]": ["well.name", "well.asset_id"],
        "sort": "name",
        "order": "asc",
        "per_page": 100,
    },
    timeout=30,
)
response.raise_for_status()

for well in response.json()["data"]:
    attributes = well["attributes"]
    print(attributes["name"], attributes["asset_id"])

JavaScript

const params = new URLSearchParams({
  visibility: 'visible',
  sort: 'name',
  order: 'asc',
  per_page: '100',
});
['active', 'paused'].forEach(value => params.append('status[]', value));
params.append('state[]', 'drilling');
['well.name', 'well.asset_id'].forEach(value => params.append('fields[]', value));

const response = await fetch(`https://api.corva.ai/v2/wells?${params}`, {
  headers: { Authorization: `API ${process.env.CORVA_API_KEY}` },
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);

const { data } = await response.json();
console.table(data.map(({ attributes }) => ({
  name: attributes.name,
  assetId: attributes.asset_id,
})));

Response fields to keep

{
  "data": [
    {
      "id": 67890,
      "type": "well",
      "attributes": {
        "name": "Example Well",
        "asset_id": 12345
      }
    }
  ]
}

The asset_id is the value to use in the Data API record query.

Alternative: find a well with /v2/assets

Use /v2/assets when the same query may include different asset types, when you need parent/child hierarchy information, or when you have an API number. Restrict the result to wells with types[]=well.

curl --get 'https://api.corva.ai/v2/assets' \
  --header "Authorization: API ${CORVA_API_KEY}" \
  --data-urlencode 'types[]=well' \
  --data-urlencode 'api_number=42-501-20130' \
  --data-urlencode 'fields[]=asset.name' \
  --data-urlencode 'fields[]=asset.asset_type' \
  --data-urlencode 'fields[]=asset.api_number' \
  --data-urlencode 'per_page=25'

{
  "data": [
    {
      "id": 12345,
      "type": "asset",
      "attributes": {
        "asset_type": "well",
        "name": "Example Well",
        "api_number": "42-501-20130"
      }
    }
  ]
}

Here, the top-level id value (12345) is the asset_id to use in the Data API.

Next: Read dataset records for the selected asset →