DrillerDB Public API v1

Every request starts with this base:

https://console.drillerdb.com/api/partner/v1

The links.self and links.next values in each response are paths, not full URLs. Prepend the host above to follow them. The OpenAPI document reports the same prefix as x-link-prefix.

Send your key in the X-API-Key header on every request.

curl -H "X-API-Key: ddb_live_example.your_secret_here" \
  "https://console.drillerdb.com/api/partner/v1/projects?limit=50"

A company administrator creates keys in the console under Settings, Automation, API Keys. The company must be on the Enterprise plan. Keys start with ddb_live_, belong to one company, and can be revoked at any time. The secret is shown once, when the key is created.

The API is available to companies on the Enterprise plan. A key belonging to any other plan returns 403 ENTERPRISE_PLAN_REQUIRED, even when the key itself is valid.

Each key carries its own scopes. A request to an endpoint outside the key's scopes returns 403 INSUFFICIENT_SCOPE. The scopes are:

• contacts:read
• contacts:write
• equipment:read
• estimates:read
• estimates:write
• inventory:read
• invoices:read
• projects:read
• projects:write
• work_orders:read
• work_orders:write

Invoices sit under a separate scope from the projects that own them, so a key can read projects without reading their money.

Each key has a per-minute limit and a per-day limit, both set when the key is created. A new key defaults to 120 requests per minute and 5,000 per day.

When a key passes either limit, the API returns 429 RATE_LIMITED with a Retry-After header giving the wait in seconds. Wait that long before retrying.

Every endpoint returns data for the company that owns the key. There is no way to read another company's records.

Each resource below is the data value an endpoint returns: one object for an item endpoint, an array of them for a list endpoint. The tables come from the same schemas the OpenAPI document publishes. A field marked nullable can be null.

A write needs a :write scope on the key. Only an admin can create a key with one, in Settings, API keys. The key then acts as its own service identity: every record it writes is attributed to that identity, which can never sign in.

Every POST needs an Idempotency-Key header of 1 to 255 characters. Retrying with the same key and the same body returns the first response and sets Idempotent-Replayed: true. The same key with a different body answers 409 IDEMPOTENCY_KEY_REUSED.

Bodies are strict: an unknown field is refused with 422 VALIDATION_FAILED. Your company always comes from the key, never from the body. An id in a body (a contact, project or user) must belong to your company, or the write is refused with 422 REFERENCE_NOT_FOUND and nothing is written.

An estimate created here is a draft. Nothing is emailed or texted; an office user reviews and sends it from DrillerDB.

List endpoints return a page of records and an opaque cursor. Read meta.next_cursor and send it back as the cursor parameter to get the next page. When meta.has_more is false, you have read everything.

{
  "data": [ ... ],
  "meta": {
    "request_id": "req_0f3a...",
    "limit": 50,
    "has_more": true,
    "next_cursor": "eyJ1cGRhdGVkX2F0Ijoi..."
  },
  "links": { "self": "...", "next": "..." }
}

limit defaults to 50 and caps at 200. Do not build the cursor yourself. Its contents are not part of the contract and can change.

Endpoints that accept updated_since return only records changed at or after the timestamp you give. The endpoint table above says which ones accept it. Use it to sync changes instead of reading every page each time.

The HTTP status is authoritative. Every response carries meta.request_id. Quote that value when you report a problem.

{
  "error": { "code": "INSUFFICIENT_SCOPE", "message": "..." },
  "meta": { "request_id": "req_0f3a..." },
  "links": { "self": "..." }
}

A record that does not exist and a record belonging to another company both return 404, with the same body. The API does not confirm that an identifier exists elsewhere.

The machine-readable contract is generated from the same route definitions this page is generated from, so the two cannot disagree. It needs no key.

https://console.drillerdb.com/api/partner/v1/openapi.json

Open the OpenAPI document. It is OpenAPI 3.1. Import it into Postman, or generate a client from it.

Work orders are ordered by identifier and accept no updated_since. The underlying records carry no reliable change timestamp.

On invoices, status is the document state as stored, such as draft, sent, or void. payment_status and balance are calculated from the invoice total and the payments recorded against it, so they report what is actually owed.

Equipment identifiers are strings. Every other resource uses an integer identifier.