Skip to main content
DumpsterVibes
Sign inRequest an invite

The DumpsterVibes API and MCP server

Connect your own website, office software or assistant tools to your company: look up bookings and customers, check dates and prices, book a roll-off dumpster, move or cancel one, and see what is owed. Every key belongs to one company and sees only that company's records.

API keys

An owner or admin makes keys in the dashboard under Tools → Connected Services → API keys: name the key, tick what it may do, and choose when it expires. The key is shown once — we keep only a fingerprint of it, so it can't be shown again. Revoke a key there and it stops working at once. A key also stops when the person who made it leaves the team or stops being an owner or admin.

Keys start dvk_live_. They act on your company's real records, so treat one like a password.

No key can charge or refund a card. A booking made through the API is paid by a pay link texted and emailed to the customer, on a net-terms customer's monthly invoice, or later by the office.

Scopes

Making requests

Send the key in the Authorization header. A key in the address is never read. Bodies and answers are JSON. Browsers can't call the API directly (no CORS): call it from your server.

curl https://dumpstervibes.com/api/v1/bookings?status=confirmed \
  -H "Authorization: Bearer dvk_live_…"

Every change needs an Idempotency-Key header: any unique string (a UUID is fine) per intended change. Send the same key again to retry safely — you get the first answer back, with Idempotent-Replayed: true, and nothing happens twice. A key is remembered for 24 hours; reusing it for a different request answers 409.

Lists are newest first and paged: pass limit (up to 100) and the next_cursor from the previous page as cursor.

Endpoints

The full contract is the OpenAPI 3.1 document at /api/v1/openapi.json, which most API tools can import.

CallWhat it doesScope
GET /api/v1/bookingsList bookingsbookings:read
POST /api/v1/bookingsCreate a bookingbookings:write
GET /api/v1/bookings/{id}Get a bookingbookings:read
POST /api/v1/bookings/{id}/rescheduleMove a delivery or pickupbookings:write
POST /api/v1/bookings/{id}/cancelCancel a bookingbookings:write
GET /api/v1/customersList or search customerscustomers:read
POST /api/v1/customersAdd a customercustomers:write
GET /api/v1/customers/{id}Get a customercustomers:read
PATCH /api/v1/customers/{id}Edit a customercustomers:write
GET /api/v1/availabilityDelivery dates and sizes for a ZIPavailability:read
GET /api/v1/quotesPrice a rentalquotes:read
GET /api/v1/invoicesList invoicesinvoices:read
GET /api/v1/invoices/{id}Get an invoice and its balanceinvoices:read

Examples

Dates and sizes for a ZIP, then a price:

curl "https://dumpstervibes.com/api/v1/availability?zip=30041" -H "Authorization: Bearer $DV_KEY"

curl "https://dumpstervibes.com/api/v1/quotes?size_id=<size id>&zip=30041&delivery_date=2026-11-10&pickup_date=2026-11-20" \
  -H "Authorization: Bearer $DV_KEY"

Book it and text the customer a pay link:

curl -X POST https://dumpstervibes.com/api/v1/bookings \
  -H "Authorization: Bearer $DV_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-order-1042" \
  -H "content-type: application/json" \
  -d '{
    "customer": { "name": "Ada Lovelace", "phone": "770-555-0100", "email": "ada@example.com" },
    "size_id": "<size id>",
    "address": "1 Main St", "city": "Cumming", "state": "GA", "zip": "30041",
    "delivery_date": "2026-11-10",
    "terms_accepted": true,
    "payment": "pay_link"
  }'

Move the delivery, or cancel an unpaid booking:

curl -X POST https://dumpstervibes.com/api/v1/bookings/<booking id>/reschedule \
  -H "Authorization: Bearer $DV_KEY" -H "Idempotency-Key: move-1042-a" \
  -H "content-type: application/json" -d '{ "delivery_date": "2026-11-12" }'

curl -X POST https://dumpstervibes.com/api/v1/bookings/<booking id>/cancel \
  -H "Authorization: Bearer $DV_KEY" -H "Idempotency-Key: cancel-1042-a" \
  -H "content-type: application/json" -d '{ "reason": "Customer changed plans" }'

A booking runs through the same rules as your office booking desk: your prices, your service area, your calendar and each size's stock. A closed or full day answers 409 date_unavailable, an address outside your area 409 out_of_area, and an address we couldn't verify 409 address_unverified — resend with "confirm_address": true to book it as typed. A booking with a payment on it is cancelled in the dashboard, where you decide the refund.

MCP server

The same key works with the remote MCP server at https://dumpstervibes.com/api/mcp (streamable HTTP). Add it to any MCP client as a custom connector with the header Authorization: Bearer dvk_live_…. In a client that reads a JSON config:

{
  "mcpServers": {
    "dumpstervibes": {
      "type": "http",
      "url": "https://dumpstervibes.com/api/mcp",
      "headers": { "Authorization": "Bearer dvk_live_…" }
    }
  }
}

The client sees only the tools the key's scopes allow. Tools that change something act for your company exactly as your office would, and each one asks for an idempotency_key so a retry never books twice.

Webhooks

To hear about changes as they happen — a new booking, a finished job, a paid invoice, a new customer — set up webhooks under Tools → Connected Services → Webhooks & Ad Tracking. They work with Zapier, Make or your own server, and every delivery is signed. Open webhooks (sign in first).

Limits and errors

Each key may make 120 requests a minute, and all of a company's keys together 300. Past that the answer is 429 with a Retry-After header.

Errors are JSON: { "error": { "code": "…", "message": "…" } }. A 503 is our fault and safe to retry; nothing was changed. A 404 means the record isn't at your company.