Skip to main content

Getting Started with the ComboCurve API

This guide will help you get started with the ComboCurve API, from obtaining your credentials to making your first API call.

Before You Begin​

To use the ComboCurve API, you will need an API Key and a Service Account Key. These can be obtained from:

  1. The API & Sync tab on the company page in your ComboCurve account
  2. Or by going directly to https://yourcompany.combocurve.com/company/api-sync (replace "yourcompany" with your company's subdomain)

You can create and download your API Key and Service Account Key by clicking the "CREATE & DOWNLOAD" button on that page.

API Specification​

You can download the full API specification including all routes and models:

Download OpenAPI 2.0 Spec (YAML)

Client Libraries​

The following official client libraries are available to simplify your integration:

ComboCurve Client - C#

For .NET applications and services

Get the C# Client

ComboCurve Client - Python

For Python applications and data science workflows

Get the Python Client

Authentication​

The ComboCurve API requires two forms of authentication for all requests:

Required Headers​

HeaderDescription
AuthorizationSigned bearer token generated using the Service Account Key
x-api-keyYour API Key

Requests that don't have valid values for these headers will fail with status code 401.

Example Authentication​

// Example of setting up authentication headers
const headers = {
  'Authorization': 'Bearer YOUR_BEARER_TOKEN',
  'x-api-key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
};

// Use these headers in your API requests
fetch('https://api.combocurve.com/v1/wells', {
  method: 'GET',
  headers: headers
})
.then(response => response.json())
.then(data => console.log(data));

Content Type​

All POST, PUT, and PATCH methods expect a JSON body, which means the Content-Type: application/json header must be set, otherwise the request will fail with status code 415.

API Limits​

Request Rate​

The API enforces the following request rate limits per client:

TypeMax requests / min
Read800
Write200

When a rate limit is exceeded, subsequent requests will fail with status code 429 until the rate comes back down to an allowed value.

Request Size​

The API enforces a maximum size of 24 MB for each request body. Requests with a larger body will fail with status code 413.

String Size​

Values for string fields are encoded in UTF-8 and their size limit is 16 KB.

Making Your First API Call​

Let's make a simple API call to retrieve a list of wells:

curl -X GET "https://api.combocurve.com/v1/wells" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json"

Example Response​

[
  {
	"id": "67a5148e6fc1d22236af43ca",
	"name": "Example Well",
	"dataSource": "ihs",
	"chosenId": "WELL-001",
	"latitude": 29.7604,
	"longitude": -95.3698,
	"createdDate": "2023-06-15T10:30:45Z",
	"lastModifiedDate": "2023-06-15T10:30:45Z"
  },
  // More wells...
],

Pagination​

Many API endpoints return collections of resources. To manage large datasets, the API implements pagination with the following parameters:

  • skip: The number of records to skip (starting from 0)
  • take: The number of items to take

Example request with pagination:

GET /v1/wells?skip=0&take=50

Query Parameters​

The API supports flexible query parameters for filtering, sorting, and searching:

Filtering​

Filter resources using field-specific parameters:

GET /v1/wells?name=Well-01

Sorting​

Sort results ascending using the sort parameter:

GET /v1/wells?sort=name

Sort results descending using the sort parameter:

GET /v1/wells?sort=-name

Complex Queries​

Combine multiple parameters for complex queries:

GET /v1/wells?dataSource=ENVERUS&sort=name&skip=0&take=50

Error Handling​

The API uses conventional HTTP response codes to indicate the success or failure of requests:

  • 2xx - Success
  • 4xx - Client error (invalid request)
  • 5xx - Server error

Error responses include a JSON object with details about the error:

{
  "timestamp": "2023-06-15T10:30:45Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Invalid parameter: name cannot be empty",
  "path": "/v1/wells"
}

Endpoints that allow the user to PUT/PATCH/POST multiple records in one request may return an HTTP 207 Multi-Status response code. These responses will include success/failure information for each record submitted in the request.

Example HTTP 207 Multi-Status response:

{
    "results": [
        {
            "status": "OK",
            "code": 200,
            "well": "673d0efb5bbb37673a853775",
            "date": "2020-03-01T00:00:00.000Z"
        },
        {
            "status": "Error",
            "code": 400,
            "errors": [
                {
                    "name": "WellNotFoundError",
                    "message": "No well was found with id `673d0efb5bbb37673a853771` in company scope",
                    "location": "[1]"
                }
            ]
        }
    ],
    "successCount": 2,
    "failedCount": 0
}

Next Steps​

Now that you're familiar with the basics of the ComboCurve API, you can:

  1. Explore the API Reference for detailed information about all available endpoints
  2. Check out the client libraries to simplify your integration
  3. Join our API Forum for support and to connect with other developers

Support​

Got feedback or questions? Please join our API Forum where you can ask questions and get help from the ComboCurve community and support team. For all other inquiries, please contact your ComboCurve Account Manager.