{ "openapi": "3.1.0", "info": { "title": "DrillerDB Public APIs", "version": "2026-10-07", "summary": "Well data, driller directory, and DrillerDB application APIs", "description": "Machine-readable description of every public DrillerDB endpoint, in three groups, each with its own server:\n\n1. drillerdb.com: free, unauthenticated JSON endpoints (well depth and water-table lookup, driller directory and license search, ZIP geocoding, platform stats, conference calendars). Errors are {error, message}. An /api path with no endpoint answers 404, and a method an endpoint does not support answers 405 with an Allow header; both bodies add hint and documentation (ApiRoutingError).\n2. app.drillerdb.com/api/v1: read-only access to a DrillerDB customer's own projects, invoices, work orders, contacts, equipment and inventory. Requires an X-API-Key issued to an Enterprise-plan company; each key carries scopes and each operation names the scope it needs in x-required-scope. Errors are {error:{code,message,hint}, meta:{request_id}, links}.\n3. enterprise.drillerdb.com/api/mcp: Model Context Protocol server for DrillerDB Enterprise (prospect intelligence), OAuth 2.1 with the mcp:read:enterprise scope.\n\nRate limits on drillerdb.com: 500 requests per IP address per 60 seconds, counted across page views and API requests together, not per endpoint. Every /api response the limiter counted carries RateLimit-Policy and RateLimit (draft-ietf-httpapi-ratelimit-headers-11); a 429 also carries Retry-After in seconds.\n\nVersioning and deprecation: the keyed APIs carry their major version in the path (app.drillerdb.com/api/v1, console.drillerdb.com/api/partner/v1). Additive changes, such as new fields, new optional parameters and new operations, stay in the current version; a breaking change ships under a new major version path. A deprecated version says so on every response with the Deprecation header (RFC 9745), the Sunset header (RFC 8594) and a Link header with rel=\"deprecation\". At least 12 months pass between the date a version first sends the Deprecation header and its Sunset date. No version is deprecated today. Details: https://drillerdb.com/docs/integrations/api-conventions.\n\nAny HTML page on drillerdb.com can be fetched as Markdown with Accept: text/markdown. Site index for agents: https://drillerdb.com/llms.txt.", "termsOfService": "https://drillerdb.com/terms", "contact": { "name": "DrillerDB", "url": "https://drillerdb.com/contact-us", "email": "support@drillerdb.com" } }, "externalDocs": { "description": "When to use DrillerDB and how an agent calls us (llms.txt)", "url": "https://drillerdb.com/llms.txt" }, "servers": [ { "url": "https://drillerdb.com", "description": "drillerdb.com public endpoints (no key)" } ], "tags": [ { "name": "Well data", "description": "Depth and water-table statistics from the public well dataset" }, { "name": "Driller directory", "description": "Find-a-Driller directory and state license records" }, { "name": "Geocoding", "description": "ZIP code resolution used by the directory" }, { "name": "Platform", "description": "Published platform counts" }, { "name": "Conferences", "description": "Industry conference calendars" }, { "name": "Projects", "description": "app.drillerdb.com/api/v1 projects (X-API-Key)" }, { "name": "Invoices", "description": "app.drillerdb.com/api/v1 invoices (X-API-Key)" }, { "name": "Work Orders", "description": "app.drillerdb.com/api/v1 work orders (X-API-Key)" }, { "name": "Contacts", "description": "app.drillerdb.com/api/v1 contacts (X-API-Key)" }, { "name": "Equipment", "description": "app.drillerdb.com/api/v1 equipment (X-API-Key)" }, { "name": "Inventory", "description": "app.drillerdb.com/api/v1 inventory (X-API-Key)" }, { "name": "Documentation", "description": "app.drillerdb.com/api/v1 documentation (X-API-Key)" }, { "name": "Enterprise MCP", "description": "Model Context Protocol server for DrillerDB Enterprise (enterprise.drillerdb.com)" } ], "paths": { "/api/well-depth-lookup": { "get": { "tags": [ "Well data" ], "operationId": "getWellDepthLookup", "summary": "Well depth and water-table statistics around a coordinate", "description": "Returns well-depth and static-water-level (water table) statistics computed from recorded wells near a US coordinate, plus a sample of the nearest wells. Public, no key. Rate limited per IP; responses are cached for up to six hours. Locations outside the United States are rejected.", "parameters": [ { "name": "lat", "in": "query", "required": true, "description": "Latitude in decimal degrees (WGS84). US only: 18 to 72.", "schema": { "type": "number", "minimum": 18, "maximum": 72 }, "example": 44.5236 }, { "name": "lng", "in": "query", "required": true, "description": "Longitude in decimal degrees (WGS84). US only: -178 to -66.", "schema": { "type": "number", "minimum": -178, "maximum": -66 }, "example": -89.5746 } ], "responses": { "200": { "description": "Statistics for the area; an insufficient_data body (still 200) when too few wells are recorded nearby to estimate; or a too_many_wells body (still 200) when the area has so many recorded wells that the statistics could not be computed in time.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/WellDepthResult" }, { "$ref": "#/components/schemas/WellDepthInsufficientData" }, { "$ref": "#/components/schemas/WellDepthTooManyWells" } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "description": "lat/lng missing or not numbers, or outside the United States.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "invalid_params", "out_of_bounds" ] } } } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "429": { "description": "Too many requests from this IP address. Wait the number of seconds in Retry-After.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } ] } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "500": { "description": "The lookup failed; retry.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "lookup_failed" ] } } } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } }, "/api/driller-license-lookup": { "get": { "tags": [ "Driller directory" ], "operationId": "lookupDrillerLicense", "summary": "Search verified well-driller licenses in a state", "description": "Searches verified state license records by driller or company name and/or license number within one state, joined to the Find-a-Driller directory. When nothing matches, nearbyDrillers lists verified drillers in that state; an empty matches array never means a driller is unlicensed. Public, no key. Rate limited per IP.", "parameters": [ { "name": "state", "in": "query", "required": true, "description": "Two-letter state abbreviation (e.g. WI) or state slug (e.g. wisconsin).", "schema": { "type": "string", "minLength": 2 }, "example": "WI" }, { "name": "name", "in": "query", "required": false, "description": "Driller or company name, at least 2 characters. Required unless license is given.", "schema": { "type": "string", "minLength": 2 }, "example": "drilling" }, { "name": "license", "in": "query", "required": false, "description": "License number, at least 2 characters. Required unless name is given.", "schema": { "type": "string", "minLength": 2 }, "example": "1234" } ], "responses": { "200": { "description": "Matches (possibly empty) and, on a miss, verified drillers in the state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DrillerLicenseLookupResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "description": "Unknown state, or neither name nor license was long enough to search.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "invalid_state", "invalid_query" ] } } } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "429": { "description": "Too many requests from this IP address. Wait the number of seconds in Retry-After.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } ] } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "500": { "description": "The lookup failed; retry.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "lookup_failed" ] } } } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } }, "/api/find-drillers/nearby": { "get": { "tags": [ "Driller directory" ], "operationId": "listNearbyDrillers", "summary": "Well drilling and pump companies near a location", "description": "Public directory of well drilling and pump service companies. Give a ZIP code or a lat/lng to get companies within the radius, sorted by relevance with distance_miles filled in; give no location to get a national list sorted by quality. Only public directory fields are returned. Public, no key; the ZIP branch is rate limited per IP.", "parameters": [ { "name": "zip", "in": "query", "required": false, "description": "Five-digit US ZIP code. Used when lat/lng are absent.", "schema": { "type": "string", "pattern": "^\\d{5}$" }, "example": "54401" }, { "name": "lat", "in": "query", "required": false, "description": "Latitude in decimal degrees.", "schema": { "type": "number", "minimum": -90, "maximum": 90 }, "example": 44.9591 }, { "name": "lng", "in": "query", "required": false, "description": "Longitude in decimal degrees.", "schema": { "type": "number", "minimum": -180, "maximum": 180 }, "example": -89.6301 }, { "name": "radius", "in": "query", "required": false, "description": "Search radius in miles when a location is given. Default and maximum useful value 150.", "schema": { "type": "number", "default": 150 }, "example": 25 }, { "name": "limit", "in": "query", "required": false, "description": "Maximum companies to return. Default 250 with a location, 150 without; capped at 250.", "schema": { "type": "integer", "minimum": 1, "maximum": 250 }, "example": 5 }, { "name": "trade", "in": "query", "required": false, "description": "Only companies in this category. Omit for every category the directory lists.", "schema": { "type": "string", "enum": [ "water_well", "geothermal", "environmental" ] }, "example": "geothermal" } ], "responses": { "200": { "description": "Companies near the location (or the national list). Empty when the directory backend is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NearbyDrillersResponse" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "description": "zip is not five digits.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "invalid_zip" ] } } } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "404": { "description": "The ZIP code is not known.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "429": { "description": "Too many requests from this IP address. Wait the number of seconds in Retry-After.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } ] } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "503": { "description": "The ZIP geocoder is temporarily unavailable.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "lookup_failed" ] } } } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } }, "/api/geo/zip": { "get": { "tags": [ "Geocoding" ], "operationId": "geocodeZip", "summary": "Resolve a US ZIP code to a coordinate", "description": "Returns the centroid, city and state for a five-digit US ZIP code. Public, no key. Rate limited per IP; results are cached for a day.", "parameters": [ { "name": "zip", "in": "query", "required": true, "description": "Five-digit US ZIP code.", "schema": { "type": "string", "pattern": "^\\d{5}$" }, "example": "54401" } ], "responses": { "200": { "description": "Centroid of the ZIP code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZipPoint" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "description": "zip is not five digits.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "invalid_zip" ] } } } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "404": { "description": "The ZIP code is not known.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "not_found" ] } } } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "429": { "description": "Too many requests from this IP address. Wait the number of seconds in Retry-After.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } ] } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "503": { "description": "The upstream geocoder is temporarily unavailable.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "lookup_failed" ] } } } ] } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } }, "/api/stats": { "get": { "tags": [ "Platform" ], "operationId": "getPlatformStats", "summary": "Platform-wide record counts", "description": "Counts of well records, directory contractors and covered states as published on the site. Constants verified against production and refreshed with the site, not live queries.", "responses": { "200": { "description": "Current published counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlatformStats" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "429": { "description": "Too many requests from this IP address. Wait the number of seconds in Retry-After.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } ] } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } }, "/api/calendar/all-conferences": { "get": { "tags": [ "Conferences" ], "operationId": "downloadAllConferencesCalendar", "summary": "iCalendar feed of water-well industry conferences", "description": "All conferences with confirmed dates for the year as one .ics file (text/calendar). The human-readable list is at /resources/driller/conferences.", "parameters": [ { "name": "year", "in": "query", "required": false, "description": "Conference year.", "schema": { "type": "string", "enum": [ "2025", "2026" ], "default": "2025" }, "example": "2026" } ], "responses": { "200": { "description": "iCalendar file.", "content": { "text/calendar": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "description": "year is not 2025 or 2026.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarError" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "404": { "description": "No conference has confirmed dates for that year.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarError" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "429": { "description": "Too many requests from this IP address. Wait the number of seconds in Retry-After.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } ] } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } }, "/api/calendar/conference/{id}": { "get": { "tags": [ "Conferences" ], "operationId": "downloadConferenceCalendar", "summary": "iCalendar file for one conference", "description": "One conference as an .ics file (text/calendar). Conference ids are the slugs used on /resources/driller/conferences, e.g. ngwa-groundwater-week.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Conference slug, e.g. ngwa-groundwater-week.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "example": "ngwa-groundwater-week" }, { "name": "year", "in": "query", "required": false, "description": "Conference year.", "schema": { "type": "string", "enum": [ "2025", "2026" ], "default": "2025" }, "example": "2026" } ], "responses": { "200": { "description": "iCalendar file.", "content": { "text/calendar": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "400": { "description": "year is not 2025 or 2026.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarError" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "404": { "description": "Unknown conference id, or no confirmed dates for that year.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CalendarError" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } }, "429": { "description": "Too many requests from this IP address. Wait the number of seconds in Retry-After.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/SiteError" }, { "properties": { "error": { "type": "string", "enum": [ "rate_limited" ] } } } ] } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimitPolicy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" } } } } } }, "/api/v1/projects": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Projects" ], "operationId": "listProjects", "x-required-scope": "projects:read", "summary": "List projects", "description": "Returns drilling projects for the API key company using cursor pagination. Requires an Enterprise-plan API key (X-API-Key header) carrying the projects:read scope.", "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" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/projects/{intWellKey}": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Projects" ], "operationId": "getProject", "x-required-scope": "projects:read", "summary": "Get a project", "parameters": [ { "$ref": "#/components/parameters/ProjectIdParam" } ], "responses": { "200": { "description": "Project detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/ProjectNotFoundResponse" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "description": "Get a project Requires an Enterprise-plan API key (X-API-Key header) carrying the projects:read scope.", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/projects/{intWellKey}/invoices": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Invoices" ], "operationId": "listProjectInvoices", "x-required-scope": "invoices:read", "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" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/ProjectNotFoundResponse" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "description": "List project invoices Requires an Enterprise-plan API key (X-API-Key header) carrying the invoices:read scope.", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/work-orders": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Work Orders" ], "operationId": "listWorkOrders", "x-required-scope": "work_orders:read", "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" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "description": "List work orders Requires an Enterprise-plan API key (X-API-Key header) carrying the work_orders:read scope.", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/work-orders/{id}": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Work Orders" ], "operationId": "getWorkOrder", "x-required-scope": "work_orders:read", "summary": "Get a work order", "parameters": [ { "$ref": "#/components/parameters/WorkOrderIdParam" } ], "responses": { "200": { "description": "Work order detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkOrderResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/WorkOrderNotFoundResponse" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "description": "Get a work order Requires an Enterprise-plan API key (X-API-Key header) carrying the work_orders:read scope.", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/contacts": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Contacts" ], "operationId": "listContacts", "x-required-scope": "contacts:read", "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" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "description": "List contacts Requires an Enterprise-plan API key (X-API-Key header) carrying the contacts:read scope.", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/contacts/{rolodexId}": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Contacts" ], "operationId": "getContact", "x-required-scope": "contacts:read", "summary": "Get a contact", "parameters": [ { "$ref": "#/components/parameters/RolodexIdParam" } ], "responses": { "200": { "description": "Contact detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/ContactNotFoundResponse" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "description": "Get a contact Requires an Enterprise-plan API key (X-API-Key header) carrying the contacts:read scope.", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/equipment": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Equipment" ], "operationId": "listEquipment", "x-required-scope": "equipment:read", "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" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "description": "List equipment Requires an Enterprise-plan API key (X-API-Key header) carrying the equipment:read scope.", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/equipment/{equipmentId}": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Equipment" ], "operationId": "getEquipment", "x-required-scope": "equipment:read", "summary": "Get equipment", "parameters": [ { "$ref": "#/components/parameters/EquipmentIdParam" } ], "responses": { "200": { "description": "Equipment detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EquipmentResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/EquipmentNotFoundResponse" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "description": "Get equipment Requires an Enterprise-plan API key (X-API-Key header) carrying the equipment:read scope.", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/inventory/items": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Inventory" ], "operationId": "listInventoryItems", "x-required-scope": "inventory:read", "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" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "description": "List inventory items Requires an Enterprise-plan API key (X-API-Key header) carrying the inventory:read scope.", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/inventory/items/{id}": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Inventory" ], "operationId": "getInventoryItem", "x-required-scope": "inventory:read", "summary": "Get inventory item", "parameters": [ { "$ref": "#/components/parameters/InventoryIdParam" } ], "responses": { "200": { "description": "Inventory item detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InventoryItemResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/ForbiddenResponse" }, "404": { "$ref": "#/components/responses/InventoryItemNotFoundResponse" }, "405": { "$ref": "#/components/responses/MethodNotAllowedResponse" }, "429": { "$ref": "#/components/responses/RateLimitedResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "description": "Get inventory item Requires an Enterprise-plan API key (X-API-Key header) carrying the inventory:read scope.", "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/openapi.json": { "servers": [ { "url": "https://app.drillerdb.com", "description": "DrillerDB application (customer data, X-API-Key)" } ], "get": { "tags": [ "Documentation" ], "operationId": "getOpenApiDocument", "summary": "Get the OpenAPI document", "description": "Public. No API key is required for this document. Served by the application at https://app.drillerdb.com/api/v1/openapi.json; this document embeds it.", "security": [], "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" } } } } } } } } }, "/api/mcp": { "servers": [ { "url": "https://enterprise.drillerdb.com", "description": "DrillerDB Enterprise (OAuth 2.1)" } ], "post": { "tags": [ "Enterprise MCP" ], "operationId": "callEnterpriseMcp", "summary": "Enterprise MCP server (Streamable HTTP transport)", "description": "Model Context Protocol endpoint for DrillerDB Enterprise customers: drilling-company prospect data, lead scores, saved lists, territories and market signals, exposed as MCP tools. Connect an MCP client to this URL; it discovers the OAuth server from the WWW-Authenticate header on the first 401 and from /.well-known/oauth-protected-resource. GET on the same path opens the server-to-client event stream and DELETE ends a session, per the MCP Streamable HTTP transport. Human setup guide: https://enterprise.drillerdb.com/docs.", "security": [ { "EnterpriseMcpOAuth": [ "mcp:read:enterprise" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" } } } }, "responses": { "200": { "description": "JSON-RPC response, as application/json or as a text/event-stream of JSON-RPC messages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "401": { "description": "Missing or invalid token. WWW-Authenticate: Bearer realm=\"enterprise-mcp\", error=..., resource_metadata=\"https://enterprise.drillerdb.com/.well-known/oauth-protected-resource\".", "headers": { "WWW-Authenticate": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpAuthError" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Company API key issued in DrillerDB Settings > API Access (Enterprise plan). Keys are scoped; the scopes a key may hold are projects:read, invoices:read, work_orders:read, contacts:read, equipment:read and inventory:read. A key lacking the scope an operation needs receives 403 INSUFFICIENT_SCOPE with meta.required_scope." }, "EnterpriseMcpOAuth": { "type": "oauth2", "description": "OAuth 2.1 authorization-code flow with PKCE (S256), as published at https://enterprise.drillerdb.com/.well-known/oauth-authorization-server. Dynamic client registration is available at https://enterprise.drillerdb.com/oauth/register. Tokens are presented as Bearer in the Authorization header. Protected-resource metadata (RFC 9728): https://enterprise.drillerdb.com/.well-known/oauth-protected-resource.", "flows": { "authorizationCode": { "authorizationUrl": "https://enterprise.drillerdb.com/oauth/authorize", "tokenUrl": "https://enterprise.drillerdb.com/oauth/token", "refreshUrl": "https://enterprise.drillerdb.com/oauth/token", "scopes": { "mcp:read:enterprise": "Read drilling-company prospect data, lead scores, lists, territories, and market signals on the user's behalf (read-only)." } } } } }, "schemas": { "ApiRoutingError": { "type": "object", "description": "Body of the 404 for an /api path on drillerdb.com that no endpoint serves, and of the 405 (with an Allow header) for a method an endpoint does not support.", "properties": { "error": { "type": "string", "enum": [ "not_found", "method_not_allowed" ] }, "message": { "type": "string" }, "hint": { "type": "string", "description": "Where to look instead." }, "documentation": { "type": "string", "format": "uri", "description": "This document." } }, "required": [ "error", "message", "hint", "documentation" ] }, "SiteError": { "type": "object", "description": "Error body returned by every drillerdb.com JSON endpoint.", "properties": { "error": { "type": "string", "description": "Machine-readable code." }, "message": { "type": "string", "description": "What went wrong and what to do." } }, "required": [ "error", "message" ] }, "CalendarError": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable reason." } }, "required": [ "error" ] }, "NearbyWell": { "type": "object", "properties": { "distance_mi": { "type": [ "number", "null" ] }, "depth_ft": { "type": [ "number", "null" ] }, "swl_ft": { "type": [ "number", "null" ], "description": "Static water level below ground, feet." }, "yield_gpm": { "type": [ "number", "null" ] }, "year": { "type": [ "integer", "null" ] }, "county": { "type": [ "string", "null" ] } }, "required": [ "distance_mi", "depth_ft", "swl_ft", "yield_gpm", "year", "county" ] }, "WellDepthResult": { "type": "object", "properties": { "well_count": { "type": "integer", "description": "Recorded wells inside the radius." }, "swl_count": { "type": "integer", "description": "Of those, wells with a static water level." }, "radius_km": { "type": "number" }, "radius_mi": { "type": "number" }, "expanded_radius": { "type": "boolean", "description": "True when the search widened to find enough wells." }, "depth_unit": { "type": "string", "enum": [ "ft" ] }, "depth_min": { "type": [ "number", "null" ] }, "depth_max": { "type": [ "number", "null" ] }, "depth_p25": { "type": [ "number", "null" ] }, "depth_p50": { "type": [ "number", "null" ], "description": "Median well depth, feet." }, "depth_p75": { "type": [ "number", "null" ] }, "has_swl": { "type": "boolean" }, "swl_p25": { "type": [ "number", "null" ] }, "swl_p50": { "type": [ "number", "null" ], "description": "Median static water level (water table), feet below ground." }, "swl_p75": { "type": [ "number", "null" ] }, "top_aquifer": { "type": [ "string", "null" ] }, "nearby": { "type": "array", "items": { "$ref": "#/components/schemas/NearbyWell" } }, "cached_at": { "type": "string", "format": "date-time" } }, "required": [ "well_count", "swl_count", "radius_km", "radius_mi", "expanded_radius", "depth_unit", "depth_min", "depth_max", "depth_p25", "depth_p50", "depth_p75", "has_swl", "swl_p25", "swl_p50", "swl_p75", "top_aquifer", "nearby", "cached_at" ] }, "WellDepthInsufficientData": { "type": "object", "description": "Returned with status 200 when too few wells are recorded near the point.", "properties": { "well_count": { "type": "integer", "enum": [ 0 ] }, "error": { "type": "string", "enum": [ "insufficient_data" ] }, "reason": { "type": "string", "enum": [ "oil_gas_only", "non_water_supply_only" ], "description": "Present when well records exist near the point but none is a water-supply well, so no water-well estimate is possible: oil_gas_only when every record is an oil or gas well, non_water_supply_only when every record is an oil or gas, monitoring, test or other non-water-supply well." }, "message": { "type": "string" } }, "required": [ "well_count", "error", "message" ] }, "WellDepthTooManyWells": { "type": "object", "description": "Returned with status 200 when the area has so many recorded wells that the statistics query ran past its time limit. No statistics are returned.", "properties": { "error": { "type": "string", "enum": [ "too_many_wells" ] }, "message": { "type": "string" } }, "required": [ "error", "message" ] }, "LicenseMatch": { "type": "object", "properties": { "licenseNumber": { "type": "string" }, "state": { "type": "string", "description": "Two-letter state." }, "licenseType": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "description": "The state record's status. unverified: the record came from a state license roster DrillerDB cannot re-check, so it is reported as neither active nor expired; expiresDate and lastVerifiedAt are null for it. Confirm it with the state board.", "enum": [ "active", "expired", "suspended", "revoked", "unverified", null ] }, "holderName": { "type": [ "string", "null" ] }, "holderType": { "type": [ "string", "null" ], "enum": [ "individual", "company", null ] }, "issuedDate": { "type": [ "string", "null" ] }, "expiresDate": { "type": [ "string", "null" ] }, "lastVerifiedAt": { "type": [ "string", "null" ] }, "sourceUrl": { "type": [ "string", "null" ], "description": "State board record, https only." }, "companyName": { "type": [ "string", "null" ] }, "companySlug": { "type": [ "string", "null" ], "description": "Directory profile: https://drillerdb.com/contractor/{companySlug}." }, "companyCity": { "type": [ "string", "null" ] } }, "required": [ "licenseNumber", "state", "licenseType", "status", "holderName", "holderType", "issuedDate", "expiresDate", "lastVerifiedAt", "sourceUrl", "companyName", "companySlug", "companyCity" ] }, "LicensedDriller": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string", "description": "Directory profile: https://drillerdb.com/contractor/{slug}." }, "city": { "type": [ "string", "null" ] }, "activeLicenses": { "type": "integer" } }, "required": [ "name", "slug", "city", "activeLicenses" ] }, "DrillerLicenseLookupResponse": { "type": "object", "properties": { "state": { "type": "string" }, "matches": { "type": "array", "items": { "$ref": "#/components/schemas/LicenseMatch" } }, "nearbyDrillers": { "type": "array", "description": "Only populated when matches is empty.", "items": { "$ref": "#/components/schemas/LicensedDriller" } } }, "required": [ "state", "matches", "nearbyDrillers" ] }, "DirectoryCompany": { "type": "object", "description": "Public directory fields only; keys absent when empty.", "properties": { "id": { "type": [ "integer", "string" ] }, "name": { "type": "string" }, "company_name": { "type": "string" }, "phone": { "type": "string" }, "slug": { "type": "string", "description": "Directory profile: https://drillerdb.com/contractor/{slug}." }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" }, "latitude": { "type": "number" }, "longitude": { "type": "number" }, "distance_miles": { "type": "number", "description": "Present when a location was given." }, "distanceMiles": { "type": "number" }, "is_featured": { "type": [ "boolean", "integer" ] }, "is_claimed": { "type": [ "boolean", "integer" ] }, "company_id": { "type": [ "integer", "string" ] }, "logo": { "type": "string" }, "service_categories": { "type": "array", "items": {} }, "recent_wells": { "type": "integer" }, "trade": { "type": "string", "enum": [ "water_well", "geothermal", "environmental" ], "description": "The category the directory lists the company under: water well, geothermal or environmental drilling." }, "google_rating": { "type": [ "number", "string" ], "description": "Average Google rating; the directory backend may serve it as a decimal string (e.g. \"4.8\")." }, "google_review_count": { "type": "integer" } }, "required": [ "id", "name" ] }, "NearbyDrillersResponse": { "type": "object", "properties": { "companies": { "type": "array", "items": { "$ref": "#/components/schemas/DirectoryCompany" } } }, "required": [ "companies" ] }, "ZipPoint": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" }, "city": { "type": "string" }, "state": { "type": "string", "description": "Two-letter state." } }, "required": [ "lat", "lng", "city", "state" ] }, "PlatformStats": { "type": "object", "properties": { "wells": { "type": "integer", "description": "Well records in the public dataset." }, "contractors": { "type": "integer", "description": "Companies in the driller directory." }, "states": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time", "description": "When this response was produced (the counts themselves are refreshed with the site)." } }, "required": [ "wells", "contractors", "states", "updated_at" ] }, "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", "description": "Stable machine-readable identifier for the failure.", "enum": [ "NOT_FOUND", "METHOD_NOT_ALLOWED", "API_KEY_REQUIRED", "INVALID_API_KEY", "API_KEY_INACTIVE", "API_KEY_EXPIRED", "ENTERPRISE_PLAN_REQUIRED", "INSUFFICIENT_SCOPE", "RATE_LIMITED", "API_NOT_READY", "INTERNAL_ERROR", "PROJECT_NOT_FOUND", "WORK_ORDER_NOT_FOUND", "CONTACT_NOT_FOUND", "EQUIPMENT_NOT_FOUND", "INVENTORY_ITEM_NOT_FOUND" ] }, "message": { "type": "string", "description": "What went wrong." }, "hint": { "type": "string", "description": "What the caller can do to resolve it." } }, "required": [ "code", "message", "hint" ] }, "ErrorMeta": { "type": "object", "additionalProperties": false, "properties": { "request_id": { "type": "string", "description": "Quote this when contacting support. Also sent as the X-Request-Id header." }, "retry_after": { "type": "integer", "description": "RATE_LIMITED only: seconds until the window resets." }, "required_scope": { "type": "string", "description": "INSUFFICIENT_SCOPE only: the scope the key is missing." }, "allowed_methods": { "type": "array", "items": { "type": "string" }, "description": "METHOD_NOT_ALLOWED only: methods the path supports." }, "missing_tables": { "type": "array", "items": { "type": "string" }, "description": "API_NOT_READY only." } }, "required": [ "request_id" ] }, "ErrorLinks": { "type": "object", "properties": { "self": { "type": "string" }, "documentation": { "type": "string", "description": "Path of this OpenAPI document." } }, "required": [ "self", "documentation" ] }, "ErrorResponse": { "type": "object", "additionalProperties": false, "properties": { "error": { "$ref": "#/components/schemas/Error" }, "meta": { "$ref": "#/components/schemas/ErrorMeta" }, "links": { "$ref": "#/components/schemas/ErrorLinks" } }, "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" ], "format": "date" }, "due_terms_raw": { "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" ] }, "JsonRpcRequest": { "type": "object", "description": "A JSON-RPC 2.0 request as defined by the Model Context Protocol.", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "integer", "null" ] }, "method": { "type": "string", "description": "MCP method, e.g. initialize, tools/list, tools/call." }, "params": { "type": "object" } }, "required": [ "jsonrpc", "method" ] }, "JsonRpcResponse": { "type": "object", "properties": { "jsonrpc": { "type": "string", "enum": [ "2.0" ] }, "id": { "type": [ "string", "integer", "null" ] }, "result": { "type": "object" }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": {} }, "required": [ "code", "message" ] } }, "required": [ "jsonrpc" ] }, "McpAuthError": { "type": "object", "properties": { "error": { "type": "string", "description": "OAuth error code, e.g. missing_token, invalid_token." }, "error_code": { "type": "string" } }, "required": [ "error" ] } }, "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" } } }, "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" } } } }, "MethodNotAllowedResponse": { "description": "The path exists but not for this HTTP method. Every route is GET (HEAD and OPTIONS are also accepted).", "headers": { "Allow": { "description": "Methods the path supports.", "schema": { "type": "string" } } }, "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" } } } } }, "headers": { "RateLimitPolicy": { "description": "Quota policy (draft-ietf-httpapi-ratelimit-headers-11, section 3): 500 requests per 60 seconds per IP address, counted across page views and API requests together, not per endpoint. Sent whenever the limiter counted the request.", "schema": { "type": "string" }, "example": "\"default\";q=500;w=60" }, "RateLimit": { "description": "Current service limit (draft-ietf-httpapi-ratelimit-headers-11, section 4): r = requests left, t = seconds until the oldest counted request leaves the 60-second window. Absent when the limiter did not count the request.", "schema": { "type": "string" }, "example": "\"default\";r=499;t=60" }, "RetryAfter": { "description": "Seconds to wait before the next request (RFC 9110, section 10.2.3).", "schema": { "type": "integer", "minimum": 1 }, "example": 45 } } }, "x-generated-by": "scripts/build-openapi.mjs", "x-legacy-spec-source": "https://app.drillerdb.com/api/v1/openapi.json" }