DrillerDB Work Orders API

openapi: 3.2.0
info:
  title: DrillerDB Public Work Orders API
  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:


    1. 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).

    2. 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}.

    3. enterprise.drillerdb.com/api/mcp: Model Context Protocol server for DrillerDB Enterprise (prospect intelligence), OAuth 2.1 with the mcp:read:enterprise scope.


    Rate 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.


    Versioning 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.


    Any 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
servers:
- url: https://drillerdb.com
  description: drillerdb.com public endpoints (no key)
tags:
- name: Work Orders
  description: app.drillerdb.com/api/v1 work orders (X-API-Key)
paths:
  /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: []
components:
  schemas:
    ErrorLinks:
      type: object
      properties:
        self:
          type: string
        documentation:
          type: string
          description: Path of this OpenAPI document.
      required:
      - self
      - documentation
    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
    ListLinks:
      type: object
      properties:
        self:
          type: string
        next:
          type: string
      required:
      - self
    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
    WorkOrderResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/WorkOrder'
        meta:
          $ref: '#/components/schemas/RequestMeta'
        links:
          $ref: '#/components/schemas/ItemLinks'
      required:
      - data
      - meta
      - links
    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
    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
    ItemLinks:
      type: object
      properties:
        self:
          type: string
      required:
      - self
    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
    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
    RequestMeta:
      type: object
      additionalProperties: false
      properties:
        request_id:
          type: string
      required:
      - request_id
  parameters:
    LimitParam:
      name: limit
      in: query
      description: Page size. Maximum 200.
      schema:
        type: integer
        default: 50
        maximum: 200
        minimum: 1
    WorkOrderIdParam:
      name: id
      in: path
      required: true
      schema:
        type: integer
    CursorParam:
      name: cursor
      in: query
      description: Opaque cursor returned from a previous list response.
      schema:
        type: string
  responses:
    WorkOrderNotFoundResponse:
      description: The requested work order does not exist in the API key company scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
    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'
    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'
  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).
externalDocs:
  description: When to use DrillerDB and how an agent calls us (llms.txt)
  url: https://drillerdb.com/llms.txt
x-generated-by: scripts/build-openapi.mjs
x-legacy-spec-source: https://app.drillerdb.com/api/v1/openapi.json