Platform API Reference

The Platform API provides wells, assets, programs, pads, rigs, drillout units, and frac fleets. Use it to discover the IDs and relationships needed for Data API queries.

Base URL: https://api.corva.ai

All examples accept either an API key or a Bearer token:

Authorization: API YOUR_API_KEY
Authorization: Bearer YOUR_JWT

Maintained reference

The parameters and examples below are verified against the current Platform API implementation. The interactive API explorer is useful for discovery, but its generated descriptions or examples may lag behind the service.

Finding wells: /v2/wells or /v2/assets

Corva exposes two synchronized views of a well. Choose the endpoint based on the job, and note that the asset ID appears in a different place.

Endpoint	Recommended use	ID used by Data API
GET /v2/wells	New well-focused integrations; lifecycle status/state; direct program, pad, rig, frac-fleet, and drillout-unit filters and relationships.	data[].attributes.asset_id
GET /v2/assets?types[]=well	Mixed program/rig/well search; legacy parent/child hierarchy; exact api_number lookup.	Top-level data[].id

The top-level ID returned by /v2/wells identifies the normalized Well record. Do not pass it to the Data API unless it happens to equal attributes.asset_id. See Find Wells and Asset IDs for complete examples of both approaches.

Response format

List endpoints return JSON:API-style resources under data. Each resource contains its platform id, type, attributes, and, when requested by the serializer, relationships or included resources.

{
  "data": [
    {
      "id": 67890,
      "type": "well",
      "attributes": {
        "name": "Example Well",
        "asset_id": 12345,
        "status": "active"
      },
      "relationships": {
        "company": { "data": { "id": 100, "type": "company" } }
      }
    }
  ]
}

The exact attributes depend on the endpoint and fields[] selection. Treat unrequested fields as optional.

Shared list parameters

Most asset list endpoints support these controls. Endpoint-specific filters are documented in the sections below.

Parameter	Type	Required	Description
ids[]	integer[]	No	Return only the listed resource IDs. Repeat the parameter for multiple values.
company	integer	No	Filter by company ID. /v2/assets uses company_id instead.
fields[]	string[]	No	Return selected fields, for example fields[]=well.name. Repeat for multiple fields.
per_page	integer	No	Number of records returned per page. Always set this explicitly for exports.
page	integer	No	Page number where supported. Follow pagination metadata instead of assuming one response contains every record.
sort	string	No	Sort field or comma-separated fields. A leading - requests descending order where supported.
order	asc or desc	No	Sorting direction. Defaults to asc on the endpoints below.
active_before	datetime	No	Return resources with last_active_at before the value.
active_after	datetime	No	Return resources with last_active_at at or after the value.

Geographic bounding-box filters require all four parameters together: lat_start, lat_end, long_start, and long_end.

List wells

GET/v2/wells

Use this endpoint to locate a well and obtain the asset_id used in Data API records.

Parameters

Parameter	Type	Required	Description
ids[]	integer[]	No	Well platform IDs.
asset_id	integer	No	Dataset asset ID. For multiple exact values, repeat asset_id[].
company	integer	No	Company ID.
program	integer	No	Program ID.
pad	integer	No	Pad ID.
drillout_unit	integer	No	Drillout unit ID.
frac_fleet	integer	No	Frac fleet ID.
status	string	No	Well status.
state	string	No	Well lifecycle state.
visibility	string	No	Well visibility.
identifier	string	No	Exact well identifier.
area	string	No	Well area.
search	string	No	Search by well name.
fields[]	string[]	No	Sparse response fields, such as well.name and well.asset_id.
last_active_drilling_before	datetime	No	Last drilling activity before the value.
last_active_drilling_after	datetime	No	Last drilling activity at or after the value.
well_start_before	integer	No	Well start before this Unix timestamp in seconds.
well_start_after	integer	No	Well start after this Unix timestamp in seconds.
per_page	integer	No	Wells per page.
sort	string	No	One of company, rig, program, name, status, visibility, identifier, or last_active_at.
order	string	No	asc or desc.

The endpoint also supports specialized stream-completion, location, archiving, and intervention filters. Use those only when the workflow requires them.

Example

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

response = requests.get(
    "https://api.corva.ai/v2/wells",
    headers={"Authorization": authorization},
    params={
        "visibility": "visible",
        "per_page": 25,
        "sort": "name",
        "fields[]": ["well.name", "well.asset_id", "well.status"],
    },
    timeout=30,
)
response.raise_for_status()
wells = response.json()["data"]

For an end-to-end walkthrough, see Find Wells and Asset IDs.

List assets

GET/v2/assets

Use the general assets endpoint when a workflow must search across multiple asset types, traverse the parent/child asset hierarchy, or find a well by an exact API number. For well-focused workflows, prefer /v2/wells.

Parameter	Type	Required	Description
types[]	string[]	No	Asset types: program, rig, or well.
ids[]	integer[]	No	Asset IDs.
status	string	No	active, idle, paused, complete, or deleting.
visibility	string	No	visible, visible_to_admin, or deleted.
program	integer	No	Program ID.
parent_asset_id	integer	No	Parent asset ID.
api_number or api_number[]	string	No	One or more API numbers. Dashes are ignored.
search	string	No	Search by asset ID, name, API number, or customer well ID.
company_id	integer	No	Company ID.
start, end	integer	No	Unix timestamp range.
fields[]	string[]	No	Sparse response fields, such as asset.name.
per_page	integer	No	Assets per page.
sort	string	No	name, last_active_at, status, rig, program, well, company, or well_end.
order	string	No	asc or desc.

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 'per_page=25'

List programs

GET/v2/programs

Parameter	Type	Description
ids[]	integer[]	Program IDs.
company	integer	Company ID.
name	string	Program name.
fields[]	string[]	Sparse response fields, such as program.name.
per_page	integer	Programs per page.
sort	string	name or company; default name.
order	string	asc or desc.

curl --get 'https://api.corva.ai/v2/programs' \
  --header "Authorization: API ${CORVA_API_KEY}" \
  --data-urlencode 'name=Delaware Basin' \
  --data-urlencode 'fields[]=program.name' \
  --data-urlencode 'per_page=25'

List pads

GET/v2/pads

Parameter	Type	Description
ids[]	integer[]	Pad IDs.
company	integer	Company ID.
program	integer	Program ID.
frac_fleet	integer	Related frac fleet ID.
current_frac_fleet	integer	Frac fleet ID for which the pad is current.
drillout_unit	integer	Related drillout unit ID.
well_ids[]	integer[]	Pads containing any listed well IDs.
search	string	Search by pad name.
active	boolean	Pads with an active well.
current	boolean	Current pads based on the pad/frac-fleet relationship.
fields[]	string[]	Sparse response fields, such as pad.name.
page, per_page	integer	Pagination controls.
sort	string	name, company, program, drillout_unit, or last_active_at.
order	string	asc or desc.

curl --get 'https://api.corva.ai/v2/pads' \
  --header "Authorization: API ${CORVA_API_KEY}" \
  --data-urlencode 'program=9001' \
  --data-urlencode 'active=true' \
  --data-urlencode 'fields[]=pad.name' \
  --data-urlencode 'per_page=25'

List rigs

GET/v2/rigs

Parameter	Type	Description
ids[]	integer[]	Rig IDs.
company	integer	Company ID.
program	integer	Program ID.
active_well	integer	Active well ID.
has_active_well	integer	Return rigs that have an active well.
search	string	Search by rig name.
app_key	string	Rigs associated with a product subscription containing this app.
active	string	Return records with an active well.
fields[]	string[]	Sparse response fields, such as rig.name.
per_page	integer	Rigs per page.
sort	string	name, program, company, or last_active_at.
order	string	asc or desc.

curl --get 'https://api.corva.ai/v2/rigs' \
  --header "Authorization: API ${CORVA_API_KEY}" \
  --data-urlencode 'has_active_well=1' \
  --data-urlencode 'fields[]=rig.name' \
  --data-urlencode 'per_page=25'

List drillout units

GET/v2/drillout_units

Parameter	Type	Description
ids[]	integer[]	Drillout unit IDs.
company	integer	Company ID.
program	integer	Program ID.
pad	integer	Pad ID.
well	integer	Well ID.
search	string	Search by drillout unit name.
app_key	string	Units associated with a product subscription containing this app.
active	string	Return records with an active well.
fields[]	string[]	Sparse response fields, such as drillout_unit.name.
per_page	integer	Units per page.
sort	string	name, program, company, pad, well, or last_active_at.
order	string	asc or desc.

curl --get 'https://api.corva.ai/v2/drillout_units' \
  --header "Authorization: API ${CORVA_API_KEY}" \
  --data-urlencode 'pad=7001' \
  --data-urlencode 'fields[]=drillout_unit.name' \
  --data-urlencode 'per_page=25'

List frac fleets

GET/v2/frac_fleets

Parameter	Type	Description
ids[]	integer[]	Frac fleet IDs.
company	integer	Company ID.
program	integer	Program ID.
pad	integer	Related pad ID.
current_pad	integer	Pad ID currently assigned to the fleet.
search	string	Search by frac fleet name.
app_key	string	Fleets associated with a product subscription containing this app.
active	string	Return records with an active well.
fields[]	string[]	Sparse response fields, such as frac_fleet.name.
per_page	integer	Fleets per page.
sort	string	name, company, or last_active_at.
order	string	asc or desc.

curl --get 'https://api.corva.ai/v2/frac_fleets' \
  --header "Authorization: API ${CORVA_API_KEY}" \
  --data-urlencode 'current_pad=7001' \
  --data-urlencode 'fields[]=frac_fleet.name' \
  --data-urlencode 'per_page=25'

Single-resource requests

Each resource also has a GET /v2/{resource}/{id} endpoint. Supply fields[] when you only need selected attributes.

curl --get 'https://api.corva.ai/v2/wells/67890' \
  --header "Authorization: API ${CORVA_API_KEY}" \
  --data-urlencode 'fields[]=well.name' \
  --data-urlencode 'fields[]=well.asset_id'

Troubleshooting

Result	What to check
Empty data	Filters, company/resource access, and pagination. An empty result is not an authentication failure.
Missing well	Increase per_page or follow pages; confirm visibility, lifecycle filters, and exact asset_id[] syntax.
Missing attribute	Remove fields[] temporarily or request the serializer field explicitly.
401	Header format, API key status, and Bearer expiry.
403	API-key permissions or the Bearer user's resource permissions.

The interactive Platform API explorer remains available for endpoints not yet covered here.