{
  "openapi": "3.1.0",
  "info": {
    "title": "Novi EVA API",
    "version": "1.0",
    "summary": "Well data, production and forecasts for a list of wells, and organization columns, from Novi EVA.",
    "description": "Read well attributes and production for a list of wells, manage your organization's own columns, and upload shapefiles. Authenticate every request with a Developer API Token from the Organization Settings page in EVA, sent in the `x-api-key` header. Errors return `{\"error\": \"<message>\"}`.",
    "contact": {
      "name": "Novi support",
      "email": "support@novilabs.com"
    }
  },
  "servers": [
    {
      "url": "https://api.novilabs.com",
      "description": "Production (not live yet; the API is in preview)"
    }
  ],
  "security": [
    {
      "api_key": []
    }
  ],
  "tags": [
    {
      "name": "Data",
      "description": "Field catalog and well attribute values for a well list."
    },
    {
      "name": "Production",
      "description": "Production history and forecast for a well list."
    },
    {
      "name": "Organization columns",
      "description": "Columns your organization defines and fills with its own values."
    },
    {
      "name": "Shapefiles",
      "description": "Shapefile upload for your organization."
    }
  ],
  "paths": {
    "/v1/data/fields": {
      "get": {
        "tags": [
          "Data"
        ],
        "operationId": "get_fields",
        "summary": "List available fields",
        "description": "Returns the fields you can request from `POST /v1/data`. Each entry's `field` is the dotted key to send, for example `Header.ResourcePlay`.",
        "parameters": [
          {
            "name": "group",
            "in": "query",
            "required": false,
            "description": "Field group to list: Header, Dates, Geology, Well Design, Frac Data, Performance or Forecast. Omit for all fields.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Field objects.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Field"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/data": {
      "post": {
        "tags": [
          "Data"
        ],
        "operationId": "post_data",
        "summary": "Get field values for wells",
        "description": "Returns one entry per well, in request order, with `data` values in the order of `fields`. A value that is not available is `\"n/a\"`. A value your subscription does not include is `\"Subscription Required\"`. A well that is not found returns `data: [\"n/a\"]`. Up to 50,000 wells per request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DataRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Values per well.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WellResult"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Too many wells.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Too many wells requested. Limited to 50,000 at a time."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/production": {
      "post": {
        "tags": [
          "Production"
        ],
        "operationId": "post_production_data",
        "summary": "Get production history and forecast for wells",
        "description": "Returns one entry per well with `id`, `history` and `forecast` arrays. With `includeForecast: false`, `forecast` is empty. A well that is not found returns empty arrays. Up to 1,000 wells per request.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProductionDataRequestBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Production per well.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/WellProduction"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Too many wells or an invalid request.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Too many wells requested. Limited to 1000 at a time."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/columns/org-defined-columns": {
      "get": {
        "tags": [
          "Organization columns"
        ],
        "operationId": "get_all_org_columns",
        "summary": "List organization columns",
        "responses": {
          "200": {
            "description": "Your organization's columns, without values.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/OrgColumnSummary"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "post": {
        "tags": [
          "Organization columns"
        ],
        "operationId": "post_org_defined_column",
        "summary": "Create an organization column",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrgColumnInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The new column.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgColumnInput"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/columns/org-defined-columns/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Column id.",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "tags": [
          "Organization columns"
        ],
        "operationId": "get_org_column",
        "summary": "Get an organization column with its values",
        "responses": {
          "200": {
            "description": "The column and its values by well.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgColumn"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidId"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      },
      "put": {
        "tags": [
          "Organization columns"
        ],
        "operationId": "put_org_defined_column",
        "summary": "Update an organization column",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrgColumnInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated column.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrgColumnInput"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidId"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/shapefile/upload": {
      "post": {
        "tags": [
          "Shapefiles"
        ],
        "operationId": "upload",
        "summary": "Upload a shapefile",
        "description": "Adds a shapefile to your organization. Send the files as `multipart/form-data`.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/UploadShapefileRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Uploaded.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "description": "Upload failed.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Developer API Token from the Organization Settings page in EVA."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "missing": {
                "value": {
                  "error": "Missing x-api-key header"
                }
              },
              "invalid": {
                "value": {
                  "error": "Invalid API key"
                }
              }
            }
          }
        }
      },
      "InvalidId": {
        "description": "Invalid column id.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "Invalid id"
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "Field": {
        "type": "object",
        "description": "A requestable field.",
        "required": [
          "field",
          "fieldName"
        ],
        "properties": {
          "field": {
            "type": "string",
            "description": "Dotted key to send in `fields`.",
            "examples": [
              "Header.ResourcePlay"
            ]
          },
          "fieldName": {
            "type": "string",
            "description": "Display name."
          }
        },
        "additionalProperties": true
      },
      "DataRequest": {
        "type": "object",
        "required": [
          "wellList",
          "fields"
        ],
        "properties": {
          "wellList": {
            "type": "array",
            "description": "Well identifiers (UWI or API), returned as you sent them.",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "100091802103W500",
                "100111403204W500"
              ]
            ]
          },
          "fields": {
            "type": "array",
            "description": "Field keys from `GET /v1/data/fields`.",
            "items": {
              "type": "string"
            },
            "examples": [
              [
                "Header.ResourcePlay",
                "Header.Status",
                "Dates.Vintage_Year"
              ]
            ]
          },
          "productionSource": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ProductionSource"
              },
              {
                "type": "null"
              }
            ]
          },
          "publicDataTrumpingOrder": {
            "type": [
              "array",
              "null"
            ],
            "description": "Which public source wins, per data category, when sources disagree.",
            "items": {
              "$ref": "#/components/schemas/PublicDataTrumpingOrder"
            }
          }
        }
      },
      "WellResult": {
        "type": "object",
        "required": [
          "uwid",
          "data"
        ],
        "properties": {
          "uwid": {
            "type": "string",
            "description": "The identifier as you sent it."
          },
          "data": {
            "type": "array",
            "description": "Values in `fields` order. `\"n/a\"` when not available, `\"Subscription Required\"` when not licensed.",
            "items": {}
          }
        }
      },
      "ProductionSource": {
        "type": "string",
        "enum": [
          "GDC",
          "Novi",
          "IHS",
          "Public",
          "Private",
          "Hybrid"
        ]
      },
      "DataSource": {
        "type": "string",
        "enum": [
          "GDC",
          "IHS"
        ]
      },
      "DataCategory": {
        "type": "string",
        "enum": [
          "Header",
          "Survey",
          "Frac",
          "Production"
        ]
      },
      "PublicDataTrumpingOrder": {
        "type": "object",
        "required": [
          "category",
          "order"
        ],
        "properties": {
          "category": {
            "$ref": "#/components/schemas/DataCategory"
          },
          "order": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DataSource"
            }
          }
        }
      },
      "ProductionDataRequestBody": {
        "type": "object",
        "required": [
          "wellList",
          "productionSource",
          "forecastSource"
        ],
        "properties": {
          "wellList": {
            "type": "array",
            "description": "Well identifiers (UWI or API), returned as you sent them.",
            "items": {
              "type": "string"
            }
          },
          "productionSource": {
            "type": "string",
            "description": "Production source, for example `GDC`.",
            "examples": [
              "GDC"
            ]
          },
          "forecastSource": {
            "type": "string",
            "description": "Forecast source, for example `GDC`.",
            "examples": [
              "GDC"
            ]
          },
          "includeForecast": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Set false to return history only."
          }
        }
      },
      "WellProduction": {
        "type": "object",
        "required": [
          "id",
          "history",
          "forecast"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Well identifier."
          },
          "history": {
            "type": "array",
            "description": "Production history records.",
            "items": {}
          },
          "forecast": {
            "type": "array",
            "description": "Forecast records. Empty when `includeForecast` is false.",
            "items": {}
          }
        },
        "additionalProperties": true
      },
      "ColumnDataType": {
        "type": "string",
        "enum": [
          "Number",
          "Text",
          "Date"
        ]
      },
      "OrgColumnSummary": {
        "type": "object",
        "required": [
          "id",
          "name",
          "subgroup",
          "dataType"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "published": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "name": {
            "type": "string",
            "examples": [
              "Test Field"
            ]
          },
          "subgroup": {
            "type": "string",
            "examples": [
              "Tests"
            ]
          },
          "dataType": {
            "$ref": "#/components/schemas/ColumnDataType"
          },
          "defaultUnit": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "bbl"
            ]
          },
          "propertyName": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "oil_production"
            ]
          },
          "withinSubgroupOrder": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32"
          }
        }
      },
      "OrgColumn": {
        "type": "object",
        "required": [
          "id",
          "name",
          "subgroup",
          "dataType",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "published": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "subgroup": {
            "type": "string"
          },
          "canBin": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "canNormalize": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "normalizeByDefault": {
            "type": [
              "number",
              "null"
            ],
            "format": "double"
          },
          "dataType": {
            "$ref": "#/components/schemas/ColumnDataType"
          },
          "defaultUnit": {
            "type": [
              "string",
              "null"
            ]
          },
          "propertyName": {
            "type": [
              "string",
              "null"
            ]
          },
          "withinSubgroupOrder": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32"
          },
          "data": {
            "type": "object",
            "description": "Values keyed by well identifier.",
            "additionalProperties": true,
            "examples": [
              {
                "100091802103W500": 100.1,
                "100111403204W500": 150.3
              }
            ]
          }
        }
      },
      "OrgColumnInput": {
        "type": "object",
        "properties": {
          "published": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "Test Field"
            ]
          },
          "subgroup": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "Tests"
            ]
          },
          "dataType": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ColumnDataType"
              },
              {
                "type": "null"
              }
            ]
          },
          "canNormalize": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "canBin": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "normalizeByDefault": {
            "type": [
              "number",
              "null"
            ],
            "format": "double"
          },
          "defaultUnit": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "bbl"
            ]
          },
          "propertyName": {
            "type": [
              "string",
              "null"
            ],
            "examples": [
              "oil_production"
            ]
          },
          "withinSubgroupOrder": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int32"
          },
          "data": {
            "type": [
              "object",
              "null"
            ],
            "description": "Values keyed by well identifier.",
            "additionalProperties": true,
            "examples": [
              {
                "100091802103W500": 100.1,
                "100111403204W500": 150.3
              }
            ]
          }
        }
      },
      "UploadShapefileRequest": {
        "type": "object",
        "properties": {
          "file": {
            "type": "array",
            "description": "Shapefile parts.",
            "items": {
              "type": "string",
              "contentMediaType": "application/octet-stream"
            }
          }
        }
      }
    }
  }
}
