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

Header	Description
Authorization	OAuth 2.0 bearer token generated using the Service Account Key
x-api-key	Your 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_OAUTH_TOKEN',
  'x-api-key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
};

// Use these headers in your API requests
fetch('https://api.combocurve.com/api/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:

Type	Max requests / min
Read	800
Write	200

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/api/v1/wells" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Authorization: Bearer YOUR_OAUTH_TOKEN" \
  -H "Content-Type: application/json"

Example Response

{
  "content": [
    {
      "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:

• page: The page number to retrieve (starting from 0)
• size: The number of items per page

Example request with pagination:

GET /api/v1/wells?page=0&size=50

Query Parameters

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

Filtering

Filter resources using field-specific parameters:

GET /api/v1/wells?name=Well-01

Sorting

Sort results using the sort parameter:

GET /api/v1/wells?sort=name,asc

Complex Queries

Combine multiple parameters for complex queries:

GET /api/v1/wells?dataSource=ENVERUS&sort=name,asc&page=0&size=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": "/api/v1/wells"
}

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.