{"openapi":"3.1.0","info":{"title":"DrillerDB Public API","version":"v1","description":"Enterprise-only, read-only REST API for DrillerDB ETL and reporting integrations."},"servers":[{"url":"https:\/\/app.drillerdb.com\/api\/v1"}],"tags":[{"name":"Projects"},{"name":"Invoices"},{"name":"Work Orders"},{"name":"Contacts"},{"name":"Equipment"},{"name":"Inventory"},{"name":"Documentation"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"parameters":{"LimitParam":{"name":"limit","in":"query","description":"Page size. Maximum 200.","schema":{"type":"integer","default":50,"maximum":200,"minimum":1}},"CursorParam":{"name":"cursor","in":"query","description":"Opaque cursor returned from a previous list response.","schema":{"type":"string"}},"UpdatedSinceParam":{"name":"updated_since","in":"query","description":"Return records updated at or after this timestamp.","schema":{"type":"string","format":"date-time"}},"ProjectIdParam":{"name":"intWellKey","in":"path","required":true,"schema":{"type":"integer"}},"WorkOrderIdParam":{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},"RolodexIdParam":{"name":"rolodexId","in":"path","required":true,"schema":{"type":"integer"}},"EquipmentIdParam":{"name":"equipmentId","in":"path","required":true,"schema":{"type":"string"}},"InventoryIdParam":{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}},"schemas":{"RequestMeta":{"type":"object","additionalProperties":false,"properties":{"request_id":{"type":"string"}},"required":["request_id"]},"ListMeta":{"type":"object","additionalProperties":false,"properties":{"request_id":{"type":"string"},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["request_id","limit","has_more","next_cursor"]},"ItemLinks":{"type":"object","properties":{"self":{"type":"string"}},"required":["self"]},"ListLinks":{"type":"object","properties":{"self":{"type":"string"},"next":{"type":"string"}},"required":["self"]},"Error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]},"ErrorResponse":{"type":"object","additionalProperties":false,"properties":{"error":{"$ref":"#\/components\/schemas\/Error"},"meta":{"$ref":"#\/components\/schemas\/RequestMeta"},"links":{"$ref":"#\/components\/schemas\/ItemLinks"}},"required":["error","meta","links"]},"Address":{"type":"object","properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"postal_code":{"type":["string","null"]}}},"Coordinates":{"type":"object","properties":{"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"updated_at":{"type":["string","null"],"format":"date-time"}}},"Project":{"type":"object","properties":{"id":{"type":"integer"},"project_number":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"priority":{"type":["integer","null"]},"customer_id":{"type":["integer","null"]},"customer_name":{"type":"string"},"address":{"$ref":"#\/components\/schemas\/Address"},"drill_type":{"type":["string","null"]},"well_type":{"type":["string","null"]},"created_by":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}},"required":["id","project_number","title","status","customer_name","address"]},"Invoice":{"type":"object","properties":{"id":{"type":"integer"},"invoice_number":{"type":"string"},"status":{"type":"string"},"payment_status":{"type":"string"},"invoice_date":{"type":["string","null"]},"due_date":{"type":["string","null"]},"invoice_total_cents":{"type":["integer","null"]},"balance":{"type":["number","null"]},"paid_amount":{"type":["number","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"last_sent_at":{"type":["string","null"],"format":"date-time"},"project_id":{"type":["integer","null"]}},"required":["id","invoice_number","status","payment_status"]},"WorkOrder":{"type":"object","properties":{"id":{"type":"integer"},"project_id":{"type":["integer","null"]},"status":{"type":"string"},"category":{"type":"string"},"work_type":{"type":["string","null"]},"field_tech":{"type":["string","null"]},"service_date":{"type":["string","null"]},"completed_at":{"type":["string","null"]},"customer_id":{"type":["integer","null"]},"customer_name":{"type":"string"},"project_title":{"type":["string","null"]},"memo":{"type":["string","null"]},"amount_billed":{"type":["string","number","null"]}},"required":["id","status","category","customer_name"]},"Contact":{"type":"object","properties":{"id":{"type":"integer"},"business_name":{"type":["string","null"]},"first_name":{"type":["string","null"]},"last_name":{"type":["string","null"]},"email":{"type":["string","null"]},"billing_email":{"type":["string","null"]},"phone":{"type":["string","null"]},"cell":{"type":["string","null"]},"address":{"$ref":"#\/components\/schemas\/Address"},"is_client":{"type":"boolean"},"is_vendor":{"type":"boolean"},"is_active":{"type":"boolean"},"updated_at":{"type":["string","null"],"format":"date-time"}},"required":["id","address","is_client","is_vendor","is_active"]},"Equipment":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"make":{"type":["string","null"]},"model":{"type":["string","null"]},"year":{"type":["integer","null"]},"status":{"type":["string","null"]},"category":{"type":["string","null"]},"assigned_employee_id":{"type":["integer","string","null"]},"last_location":{"$ref":"#\/components\/schemas\/Coordinates"},"updated_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":["string","null"],"format":"date-time"}},"required":["id","name","last_location"]},"InventoryItem":{"type":"object","properties":{"id":{"type":"integer"},"item_id":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"category":{"type":["string","null"]},"current_quantity":{"type":["number","null"]},"min_quantity":{"type":["number","null"]},"max_quantity":{"type":["number","null"]},"unit":{"type":["string","null"]},"unit_price":{"type":["number","null"]},"location":{"type":["string","null"]},"sku":{"type":["string","null"]},"is_active":{"type":["boolean","null"]},"last_restocked_date":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"},"updated_at":{"type":["string","null"],"format":"date-time"}},"required":["id","item_id","name"]},"ProjectListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Project"}},"meta":{"$ref":"#\/components\/schemas\/ListMeta"},"links":{"$ref":"#\/components\/schemas\/ListLinks"}},"required":["data","meta","links"]},"ProjectResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Project"},"meta":{"$ref":"#\/components\/schemas\/RequestMeta"},"links":{"$ref":"#\/components\/schemas\/ItemLinks"}},"required":["data","meta","links"]},"InvoiceListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Invoice"}},"meta":{"$ref":"#\/components\/schemas\/ListMeta"},"links":{"$ref":"#\/components\/schemas\/ListLinks"}},"required":["data","meta","links"]},"WorkOrderListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/WorkOrder"}},"meta":{"$ref":"#\/components\/schemas\/ListMeta"},"links":{"$ref":"#\/components\/schemas\/ListLinks"}},"required":["data","meta","links"]},"WorkOrderResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/WorkOrder"},"meta":{"$ref":"#\/components\/schemas\/RequestMeta"},"links":{"$ref":"#\/components\/schemas\/ItemLinks"}},"required":["data","meta","links"]},"ContactListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Contact"}},"meta":{"$ref":"#\/components\/schemas\/ListMeta"},"links":{"$ref":"#\/components\/schemas\/ListLinks"}},"required":["data","meta","links"]},"ContactResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Contact"},"meta":{"$ref":"#\/components\/schemas\/RequestMeta"},"links":{"$ref":"#\/components\/schemas\/ItemLinks"}},"required":["data","meta","links"]},"EquipmentListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/Equipment"}},"meta":{"$ref":"#\/components\/schemas\/ListMeta"},"links":{"$ref":"#\/components\/schemas\/ListLinks"}},"required":["data","meta","links"]},"EquipmentResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/Equipment"},"meta":{"$ref":"#\/components\/schemas\/RequestMeta"},"links":{"$ref":"#\/components\/schemas\/ItemLinks"}},"required":["data","meta","links"]},"InventoryItemListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/InventoryItem"}},"meta":{"$ref":"#\/components\/schemas\/ListMeta"},"links":{"$ref":"#\/components\/schemas\/ListLinks"}},"required":["data","meta","links"]},"InventoryItemResponse":{"type":"object","properties":{"data":{"$ref":"#\/components\/schemas\/InventoryItem"},"meta":{"$ref":"#\/components\/schemas\/RequestMeta"},"links":{"$ref":"#\/components\/schemas\/ItemLinks"}},"required":["data","meta","links"]}},"responses":{"UnauthorizedResponse":{"description":"Missing, invalid, inactive, or expired API key.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"ForbiddenResponse":{"description":"The API key lacks scope or the company is not entitled to API access.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"RateLimitedResponse":{"description":"The key exceeded its configured rate limits.","headers":{"Retry-After":{"description":"Seconds until the current rate limit window resets.","schema":{"type":"integer"}}},"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"ServiceUnavailableResponse":{"description":"The public API schema has not been migrated in this environment yet.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"ProjectNotFoundResponse":{"description":"The requested project does not exist in the API key company scope.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"WorkOrderNotFoundResponse":{"description":"The requested work order does not exist in the API key company scope.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"ContactNotFoundResponse":{"description":"The requested contact does not exist in the API key company scope.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"EquipmentNotFoundResponse":{"description":"The requested equipment record does not exist in the API key company scope.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}},"InventoryItemNotFoundResponse":{"description":"The requested inventory item does not exist in the API key company scope.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ErrorResponse"}}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"\/projects":{"get":{"tags":["Projects"],"operationId":"listProjects","summary":"List projects","description":"Returns drilling projects for the API key company using cursor pagination.","parameters":[{"$ref":"#\/components\/parameters\/LimitParam"},{"$ref":"#\/components\/parameters\/CursorParam"},{"$ref":"#\/components\/parameters\/UpdatedSinceParam"}],"responses":{"200":{"description":"A paginated list of projects.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ProjectListResponse"}}}},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/projects\/{intWellKey}":{"get":{"tags":["Projects"],"operationId":"getProject","summary":"Get a project","parameters":[{"$ref":"#\/components\/parameters\/ProjectIdParam"}],"responses":{"200":{"description":"Project detail.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ProjectResponse"}}}},"404":{"$ref":"#\/components\/responses\/ProjectNotFoundResponse"},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/projects\/{intWellKey}\/invoices":{"get":{"tags":["Invoices"],"operationId":"listProjectInvoices","summary":"List project invoices","parameters":[{"$ref":"#\/components\/parameters\/ProjectIdParam"},{"$ref":"#\/components\/parameters\/LimitParam"},{"$ref":"#\/components\/parameters\/CursorParam"}],"responses":{"200":{"description":"A paginated list of invoices linked to a project.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/InvoiceListResponse"}}}},"404":{"$ref":"#\/components\/responses\/ProjectNotFoundResponse"},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/work-orders":{"get":{"tags":["Work Orders"],"operationId":"listWorkOrders","summary":"List work orders","parameters":[{"$ref":"#\/components\/parameters\/LimitParam"},{"$ref":"#\/components\/parameters\/CursorParam"}],"responses":{"200":{"description":"A paginated list of service work orders.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/WorkOrderListResponse"}}}},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/work-orders\/{id}":{"get":{"tags":["Work Orders"],"operationId":"getWorkOrder","summary":"Get a work order","parameters":[{"$ref":"#\/components\/parameters\/WorkOrderIdParam"}],"responses":{"200":{"description":"Work order detail.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/WorkOrderResponse"}}}},"404":{"$ref":"#\/components\/responses\/WorkOrderNotFoundResponse"},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/contacts":{"get":{"tags":["Contacts"],"operationId":"listContacts","summary":"List contacts","parameters":[{"$ref":"#\/components\/parameters\/LimitParam"},{"$ref":"#\/components\/parameters\/CursorParam"},{"$ref":"#\/components\/parameters\/UpdatedSinceParam"}],"responses":{"200":{"description":"A paginated list of contacts.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ContactListResponse"}}}},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/contacts\/{rolodexId}":{"get":{"tags":["Contacts"],"operationId":"getContact","summary":"Get a contact","parameters":[{"$ref":"#\/components\/parameters\/RolodexIdParam"}],"responses":{"200":{"description":"Contact detail.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ContactResponse"}}}},"404":{"$ref":"#\/components\/responses\/ContactNotFoundResponse"},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/equipment":{"get":{"tags":["Equipment"],"operationId":"listEquipment","summary":"List equipment","parameters":[{"$ref":"#\/components\/parameters\/LimitParam"},{"$ref":"#\/components\/parameters\/CursorParam"},{"$ref":"#\/components\/parameters\/UpdatedSinceParam"}],"responses":{"200":{"description":"A paginated list of equipment records.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EquipmentListResponse"}}}},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/equipment\/{equipmentId}":{"get":{"tags":["Equipment"],"operationId":"getEquipment","summary":"Get equipment","parameters":[{"$ref":"#\/components\/parameters\/EquipmentIdParam"}],"responses":{"200":{"description":"Equipment detail.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/EquipmentResponse"}}}},"404":{"$ref":"#\/components\/responses\/EquipmentNotFoundResponse"},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/inventory\/items":{"get":{"tags":["Inventory"],"operationId":"listInventoryItems","summary":"List inventory items","parameters":[{"$ref":"#\/components\/parameters\/LimitParam"},{"$ref":"#\/components\/parameters\/CursorParam"},{"$ref":"#\/components\/parameters\/UpdatedSinceParam"}],"responses":{"200":{"description":"A paginated list of inventory items.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/InventoryItemListResponse"}}}},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/inventory\/items\/{id}":{"get":{"tags":["Inventory"],"operationId":"getInventoryItem","summary":"Get inventory item","parameters":[{"$ref":"#\/components\/parameters\/InventoryIdParam"}],"responses":{"200":{"description":"Inventory item detail.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/InventoryItemResponse"}}}},"404":{"$ref":"#\/components\/responses\/InventoryItemNotFoundResponse"},"401":{"$ref":"#\/components\/responses\/UnauthorizedResponse"},"403":{"$ref":"#\/components\/responses\/ForbiddenResponse"},"429":{"$ref":"#\/components\/responses\/RateLimitedResponse"},"503":{"$ref":"#\/components\/responses\/ServiceUnavailableResponse"}}}},"\/openapi.json":{"get":{"tags":["Documentation"],"operationId":"getOpenApiDocument","summary":"Get the OpenAPI document","responses":{"200":{"description":"OpenAPI specification for the public API.","content":{"application\/json":{"schema":{"type":"object","properties":{"openapi":{"type":"string"},"info":{"type":"object"},"paths":{"type":"object"},"components":{"type":"object"}}}}}}}}}}}