Developers

Start here

1. Get a sandbox key: partners on the partner dashboard, distributors on Supplier → Organization. New to Ducto? Get in touch.
2. Call https://www.ducto.org/api/v1 with Authorization: Bearer <key>. Sandbox keys start dk_test_, live keys dk_live_; every response says which in Ducto-Mode.
3. Send an Idempotency-Key with every POST (8 to 128 characters, new for each new request). A retry with the same key and body gets the first answer back for 24 hours; the same key with a different body is refused.
4. Run a whole project in the sandbox in minutes, then switch to a live key.

Guides

• Retailers: sell it installed and permittedStores that sell the equipment and want an installed, permitted heat pump in their own cart. You stay the merchant for the equipment and ship it; Ducto sizes the home, checks the cart fits, books and pays a licensed installer, handles permits and keeps the home record.
• Manufacturers: product data, certifications and registrationsBrands verified in Ducto's brand program. Your key speaks only for your verified brands.
• Distributors: stock, prices and purchase ordersSuppliers that ship equipment for Ducto's own orders. Your supplier account's owner issues keys on Supplier → Organization.
• Utilities and programs: quotes, compliance and the home recordUtilities, efficiency programs and referral partners that send homeowners to Ducto or need what an install requires.

The contract

• OpenAPI 3.1: /api/v1/openapi.json, rendered in the API reference.
• TypeScript SDK: @ducto/sdk (packages/sdk), generated from the contract: typed calls, idempotency keys made for you, errors with stable codes, and webhook signature checks.
• Errors are RFC 9457 problems (application/problem+json) with a stable code; show people the detail.
• Versioning: within v1, changes are additive only (new endpoints, new optional fields, new values). A deprecated endpoint keeps working at least 12 months and says so in Deprecation and Sunset headers. See the changelog.
• Limits: 60 requests a minute per mode unless your agreement says otherwise; 429 responses carry Retry-After.
• Health and targets: status.